<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE>The GNU Gatekeeper</TITLE>


</HEAD>
<BODY>
<H1>The GNU Gatekeeper</H1>

<H2>Maintainer of this manual:
<A HREF="http://www.willamowius.de/gnugk-consulting.html">Jan Willamowius</A>
<CODE>
<A HREF="mailto:jan@willamowius.de">&lt;jan@willamowius.de&gt;</A></CODE></H2>Version 2.3.2, May 2010
<P><HR>
<EM>This User Manual
explains how to compile, install, configure and monitor
<A HREF="http://www.gnugk.org/">the GNU Gatekeeper (GnuGk)</A>.</EM>
<HR>
<H2><A NAME="s1">1. Introduction</A></H2>

<P>
<H2>1.1 About</H2>

<P><B>
<A HREF="http://www.gnugk.org/">The GNU Gatekeeper</A></B>
is an open-source project that implements a H.323 gatekeeper. A gatekeeper
provides call control services to H.323 endpoints and is an integral part of
most useful Internet telephony installations that are based on the H.323
standard.
<P>According to Recommendation H.323, a gatekeeper shall provide the
following services:
<UL>
<LI>Address Translation</LI>
<LI>Admissions Control</LI>
<LI>Bandwidth Control</LI>
<LI>Zone Management</LI>
<LI>Call Control Signaling</LI>
<LI>Call Authorization</LI>
<LI>Bandwidth Management</LI>
<LI>Call Management</LI>
</UL>
<P>The GNU Gatekeeper implements most of these functions
based on the
<A HREF="http://sourceforge.net/projects/openh323">OpenH323</A>
protocol stack.
<P>Recommendation H.323 is an international standard published by the 
<A HREF="http://www.itu.int/">ITU</A>.  It is a communications standard for
audio, video, and data over the Internet.  See also Paul Jones' 
<A HREF="http://www.packetizer.com/voip/h323/papers/primer/">A Primer on the H.323 Series Standard</A>.
<P>For a detailed description of what a gatekeeper does, see
<A HREF="http://www.iec.org/online/tutorials/h323/topic06.html">here</A>.
<P>
<H2>1.2 Copyright</H2>

<P>The GNU Gatekeeper is covered by the 
<A HREF="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General Public License version 2</A> (GNU GPL v2).  In addition, we explicitly
grant the right to link this code to the OpenH323/H323Plus and OpenSSL
library.
<P>Some protocols implemented in the GNU Gatekeeper are covered by patents
(especially the firewall / NAT traversal protocols).  To the best of our
knowledge, the GNU Gatekeeper Project has a valid license for all its
releases, but users making derived versions of this code must ensure that
they have a valid license before enabling those features.
<P>Generally speaking, the GNU GPL allows you to copy, distribute, resell or
modify the software, but it requires that all derived works must also be
published under the GNU GPL.  This means that you must publish full source
for all extensions to the gatekeeper and for all programs where you
incorporate code from the GNU Gatekeeper.  See the file COPYING for details.
<P>If that's not what you want, you must interface to the gatekeeper through
the status port and communicate with it via TCP.  This allows you to
integrate basic functionality into the gatekeeper (and provide source for
that) but keep other parts of your application private.
<P>
<H2>1.3 Name</H2>

<P>The full name of this project is <EM>GNU Gatekeeper</EM>, but it may also be
referred to as <EM>GnuGk</EM>.  The use of "GNU" in the name is to emphasize
that this is free software.
<P>
<H2><A NAME="download"></A> 1.4 Download</H2>

<P>The newest version is available at
<A HREF="http://www.gnugk.org/h323download.html">the download page</A>.
<P>The very latest source code is in the CVS at 
<A HREF="http://openh323gk.cvs.sourceforge.net/openh323gk/openh323gk/">Sourceforge Web-GUI</A>.  Beware - that's the bleeding edge.
<P>You can also download executables for a number of operating systems from
<A HREF="http://www.gnugk.org/h323download.html">the download page</A>.
<P>
<H2>1.5 Mailing Lists</H2>

<P>There are two mailing list for the project, one for developers and one for users.
<P>General user questions should be sent to the 
<A HREF="mailto:Openh323gk-users@sourceforge.net">users mailing list</A>. 
You can find the list archive 
<A HREF="https://sourceforge.net/mailarchive/forum.php?forum_name=openh323gk-users">here</A>.  To join this mailing list, click 
<A HREF="https://lists.sourceforge.net/lists/listinfo/openh323gk-users">here</A>.
<P>To report problems or submit bugs/patches, send email to the
<A HREF="mailto:Openh323gk-developer@sourceforge.net">developers mailing list</A>.  The list archive is 
<A HREF="http://sourceforge.net/mailarchive/forum.php?forum_name=openh323gk-developer">here</A>.  Please send user questions to the users mailing list and keep
this list for development!  If you want to contribute to the project, please
<A HREF="http://lists.sourceforge.net/lists/listinfo/openh323gk-developer">join the developers mailing list</A>.
<P>
<H2>1.6 Contributors</H2>

<P>The current project coordinator is
<A HREF="http://www.willamowius.de/gnugk-consulting.html">Jan Willamowius</A>
<CODE>
<A HREF="mailto:jan@willamowius.de">&lt;jan@willamowius.de&gt;</A></CODE>
<P>The main features and functions of version 2.0 are contributed by Chih-Wei
Huang <CODE>
<A HREF="mailto:cwhuang@linux.org.tw">&lt;cwhuang@linux.org.tw&gt;</A></CODE> and Citron Network Inc., including
thread-safe registration and call tables, new routed mode architecture,
H.323 proxy, H.235 authentication and MySQL backend.
<P>Michal Zygmuntowicz <CODE>
<A HREF="mailto:m.zygmuntowicz@onet.pl">&lt;m.zygmuntowicz@onet.pl&gt;</A></CODE> has done some great work on
Radius support and other improvements.
<P>The initial version of the gatekeeper had been developed by
Xiang Ping Chen, Joe Metzger and Rajat Todi.
<P>
<H2><A NAME="s2">2. Compiling and Installing</A></H2>

<P>
<H2>2.1 Pre-requisites for Compiling</H2>

<P>To build the gatekeeper you need PWLib and OpenH323 or PTLib and H323Plus.
Please see
<A HREF="http://www.gnugk.org/compiling-gnugk.html">http://www.gnugk.org/compiling-gnugk.html</A>
for up-to-date information on required library versions.
<P><B>NOTE:</B> In order to use any H.460 features, you must build with H323Plus.
<P>To successfully compile the GNU Gatekeeper you must first compile the pre-requisites in this order:
<P>
<OL>
<LI>PWLib or PTLib</LI>
<LI>OpenH323 or H323Plus</LI>
</OL>
<P>On Unix, run <CODE>configure</CODE> and <CODE>make debug</CODE> or <CODE>make optnoshared</CODE>
in the gatekeeper directory to build debug or release version, respectively.
<P><B>NOTE:</B>  You must use either <CODE>make debug</CODE> or <CODE>make optnoshared</CODE>
throughout the compile process.  For example, if a library is compiled with <CODE>make
optnoshared</CODE> then everything must be compiled the same way.
<P>
<P>
<H2>2.2 Installing on Unix</H2>

<P>The first step is to get an executable: You can either download an executable for your flavour of Unix from
<A HREF="http://www.gnugk.org/h323download.html">gnugk.org</A>, use the executable your distribution
provides or compile the GNU Gatekeeper yourself. For simple installations or to try the features of the gatekeeper,
using pre-built executables shouldn't pose any issues, but for professional installations it is always recommended
that you self-compile GnuGk.
<P>
<H3>Installing a binary of GnuGk</H3>

<P>Copy the executable to the directory you like and create a config file.
There are several config examples and auto startup scripts in the <CODE>etc/</CODE> subdirectory
of the source tree. See section 
<A HREF="#config">Configuration File</A>
for detailed explanations of the parameters.
<P>For example you may copy GnuGk to <CODE>/usr/sbin/</CODE>, create a config in
<CODE>/etc/gatekeeper.ini</CODE> and start it by
<BLOCKQUOTE><CODE>
<PRE>
/usr/sbin/gnugk -c /etc/gatekeeper.ini -o /var/log/gnugk.log -ttt
</PRE>
</CODE></BLOCKQUOTE>

See section 
<A HREF="#commandline">Command Line Options</A> for details on the command line options.
<P>
<H3>Compiling the Gatekeeper</H3>

<P><B>NOTE:</B>  you must use GCC 3.3.x or later.
<P>You are strongly encouraged to execute <CODE>make debugdepend</CODE> or <CODE>make optdepend</CODE>
in the gatekeeper directory before starting actual compilation - these commands
build appropriate dependency lists, so any CVS updates to the source code will force
all affected files to get recompiled and will prevent the resulting binary from being compiled
with a mix of old and updated headers.
<P>Type <CODE>configure --help</CODE> to see a detailed list of all compile-time
options. You can use them to enable or disable features of the gatekeeper.
For example, if you do not need RADIUS just type: <CODE>configure --disable-radius</CODE>.<BR>
<P>In order to use the gatekeeper under heavy load, enabling the LARGE_FDSET feature
(only available on Unix) is recommended (configure --with-large-fdset=4096). Some systems
also need to use ulimit in order to allow more than 1024 sockets to be allocated for 
a single process.
Maximum LARGE_FDSET value for voice calls should be calculated 
based upon predicted maximum sockets usage using the following formula:
<BLOCKQUOTE><CODE>
<PRE>
MAX_NUMBER_OF_CONCURRENT_CALLS * 10 * 120%

Where:
10 = 2 sockets for Q.931 + 2 sockets for H.245 + 6 sockets for RTP
</PRE>
</CODE></BLOCKQUOTE>

So for 100 concurrent voice calls you don't need more than 1024 sockets in the
LARGE_FDSET.
<P>As a final step, you must either use <CODE>make debug</CODE> or <CODE>make optnoshared</CODE>, depending
on how you compiled the libraries.
<P>
<H2>2.3 Installing on Windows</H2>

<P>The first step is to obtain the executable program; you can either download it from
<A HREF="http://www.gnugk.org/h323download.html">gnugk.org</A>
or compile the GNU Gatekeeper yourself.
<P>There are two versions of the gatekeeper available: A regular program and a service.
<P>
<H3>Installing as a Program</H3>

<P>These are the steps for a manual installation:
<P>Copy <CODE>gnugk.exe</CODE> to the folder you like and create a config file.
There are several config examples in the <CODE>etc/</CODE> subdirectory of the download archive.
See section 
<A HREF="#config">Configuration File</A>
for detailed explanations.
<P>Then start the gatekeeper manually from the command line ('cmd.exe') or create a batch file to start it.
<P>For example you may copy GnuGk to <CODE>C:\GnuGk\</CODE>, create a config in
<CODE>C:\GnuGk\gatekeeper.ini</CODE> and start it as
<BLOCKQUOTE><CODE>
<PRE>
C:\GnuGk\gnugk.exe -c C:\GnuGk\gatekeeper.ini -o C:\GnuGk\gnugk.log -ttt
</PRE>
</CODE></BLOCKQUOTE>

See section 
<A HREF="#commandline">Command Line Options</A> for details on the command line options.
<P>Remember to add GnuGk as an exception for the Windows Firewall so it can communicate freely with the network.
<P>
<H3>Installing as a Service</H3>

<P>These are the steps for a manual installation; there may be a binary version of the Gatekeeper-as-service which includes a GUI
installer program available in the download location.
<P>First, ensure that you have the service version of GnuGk before you proceed.
<P>Copy <CODE>gnugk.exe</CODE> to the folder you like and create a config file named <CODE>gatekeeper.ini</CODE> in the same folder.
See section 
<A HREF="#config">Configuration File</A>
for detailed explanations. When you run GnuGk as a service, no command line options are available.
<P>To register the service, run the following command from the command line ('cmd.exe'):
<P>
<BLOCKQUOTE><CODE>
<PRE>
gnugk.exe install notray
</PRE>
</CODE></BLOCKQUOTE>
<P>Your service is now installed and will be started on the next reboot, or you
may start it manually using the Windows Control Panel -> Services function.  On Windows Vista and
Windows 7, you may have to disable UAC during the service installation.
<P>When running GnuGk as a service, it will always look for a config file named <CODE>gatekeeper.ini</CODE>
in the current directory. Any changes to the trace level and location of the trace file must be made in the 
config file rather than the command line.
<P>Remember to add GnuGk as an exception for the Windows Firewall so it can communicate freely with the network.
<P>
<H3>Compiling the Gatekeeper</H3>

<P>Once you have compiled the pre-requisites as specified at the beginning of
this section and have the appropriate include/library paths configured, open and
compile one of the provided solution files (<CODE>.sln</CODE>) for your version of
Microsoft Visual Studio.  If you need MySQL or PostgreSQL support,
install/compile appropriate client libraries before you compile GnuGk.
<P>
<H2>2.4 The addpasswd utility</H2>

<P>Status port authentication and many other authentication modules, like SimplePasswordAuth, require
encrypted passwords to be stored in the gatekeeper configuration file.
The gatekeeper also supports encryption of all passwords
in the config. The <CODE>addpasswd</CODE> utility is required to generate and store 
these encrypted passwords. This utility is included with the gatekeeper 
and can be compiled using:
<BLOCKQUOTE><CODE>
<PRE>
$ make addpasswd
</PRE>
</CODE></BLOCKQUOTE>
<P>The usage is as follows:
<BLOCKQUOTE><CODE>
<PRE>
$ addpasswd CONFIG SECTION KEYNAME PASSWORD
</PRE>
</CODE></BLOCKQUOTE>
<P>Example 1: 'gkadmin' user with 'secret' password has to be added 
to the [GkStatus::Auth] config section to enable authentication on the status port:
<BLOCKQUOTE><CODE>
<PRE>
$ addpasswd gatekeeper.ini GkStatus::Auth gkadmin secret
</PRE>
</CODE></BLOCKQUOTE>
<P>Example 2: 'joe' user with 'secret' password has to be added to the [Password]
config section to enable endpoint authentication:
<BLOCKQUOTE><CODE>
<PRE>
$ addpasswd gatekeeper.ini Password joe secret
</PRE>
</CODE></BLOCKQUOTE>
<P>Example 3: An encrypted shared secret is added to a RadAuth config section:
<BLOCKQUOTE><CODE>
<PRE>
$ addpasswd gatekeeper.ini RadAuth SharedSecret VerySecretPassword
</PRE>
</CODE></BLOCKQUOTE>
<P>IMPORTANT: The <CODE>KeyFilled</CODE> variable defines a default initializer for password
encryption keys. It can be omitted in the config (and therefore defaults to 0),
but if it is specified, each time it changes, encrypted passwords have to be
regenerated (encrypted again using the <CODE>addpasswd</CODE> utility).
<H2><A NAME="s3">3. Getting Started (Tutorial)</A></H2>

<P>
<H2>3.1 A first simple experiment</H2>

<P>To confirm that all components are up and running, get
2 Linux workstations, both connected to the LAN.
In addition to GnuGk the examples use a softphone called "OhPhone".
On the first machine run the 
<A HREF="http://www.gnugk.org/">gatekeeper</A>
in direct mode:
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > gnugk -ttt
</PRE>
</CODE></BLOCKQUOTE>
<P>The "<CODE>-ttt</CODE>" option tells the gatekeeper that it should be verbose with the debug output
to the console. You can direct the output to a file with "<CODE>-o logfilename.log</CODE>"
<P>Now start OhPhone on another console:
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > ohphone -l -a -u jan
</PRE>
</CODE></BLOCKQUOTE>
<P>OhPhone is now listening (<CODE>-l</CODE>) for calls and will automatically accept
them (<CODE>-a</CODE>).  It has also registered with the gatekeeper as user jan.  OhPhone
will attempt to automatically locate the gatekeeper, but if the auto
detect fails, use "<CODE>-g 1.2.3.4</CODE>" to specify the IP address of the gatekeeper.
<P>On the second machine run ohphone this way:
<P>
<BLOCKQUOTE><CODE>
<PRE>
peter@machine2 > ohphone -u peter jan
</PRE>
</CODE></BLOCKQUOTE>
<P>The second instance of OhPhone registers with the auto detected
gatekeeper as user peter and tries to call user jan.
The gatekeeper will resolve the username to the IP address from
where user jan has registered (machine1 in this case) and OhPhone
will call the other instance of OhPhone on machine1.
<P>The instance of OhPhone on machine1 will automatically accept the call and Peter and Jan can chat.
<P>
<H2>3.2 Using the Status interface to monitor the gatekeeper</H2>

<P>The status interface presents a text-based means of interacting with an already-running gatekeeper.
<P>On a new console on machine1 we use telnet to connect to the gatekeeper:
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > telnet machine1 7000
</PRE>
</CODE></BLOCKQUOTE>
<P>You should receive an "Access forbidden!" message because access to the status port is restricted by default.
<P>Create a file called <CODE>gatekeeper.ini</CODE> in the
directory where we start the gatekeeper.
<CODE>gatekeeper.ini</CODE> will contain the following 4 lines:
<P>
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Main]
Fortytwo=42
[GkStatus::Auth]
rule=allow
</PRE>
</CODE></BLOCKQUOTE>
<P>Stop the gatekeeper with Ctrl-C and restart it, but specify that it should use the <CODE>gatekeeper.ini</CODE> we just created:
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > gnugk -ttt -c ./gatekeeper.ini
</PRE>
</CODE></BLOCKQUOTE>
<P>Use telnet to connect to port 7000 and you should now be allowed to connect to the gatekeeper:
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 >  telnet localhost 7000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Version:
Gatekeeper(GNU) Version(2.3.1) Ext(pthreads=1,radius=1,mysql=0,pgsql=0,firebird=0,odbc=0,sqlite=0,large_fdset=0,crypto/ssl=1,h46018=1,h46023=1) Build(Aug 12 2009, 09:30:37) Sys(Linux i686 2.6.28-14-generic)
Startup: Tue, 25 Aug 2009 15:30:44 -0500   Running: 2 days 21:30:50
;
</PRE>
</CODE></BLOCKQUOTE>
<P>Now repeat the first experiment where Peter calls Jan and see which
messages are handled by the gatekeeper in non-routed mode.
<P>There are a number of commands that can be issued in the telnet session - type "help" to see them.
<P>To end the telnet session with the gatekeeper type "quit" and hit Enter.
<P>However, the example configuration file we created is very insecure because it has a default <B>allow</B> rule, so there are no
restrictions on who can connect and which commands they may execute.
<P>Change the configuration file to:
<P>
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Main]
Fortytwo=42
[GkStatus::Auth]
rule=password
gkadmin=QC7VyAo5jEw=
</PRE>
</CODE></BLOCKQUOTE>
<P>The 5th line was added by the addpasswd utility, which was used to create a user "gkadmin" with 
password "secret".  This change now enforces authentication to the status port.
<P>Restart the gatekeeper with this new configuration and perform the telnet again.
You should now be prompted for a username and password:
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 >  telnet localhost 7000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.

GnuGk login: gkadmin
Password: secret
Version:
Gatekeeper(GNU) Version(2.3.1) Ext(pthreads=1,radius=1,mysql=0,pgsql=0,firebird=0,odbc=0,sqlite=0,large_fdset=0,crypto/ssl=1,h46018=1,h46023=1) Build(Aug 12 2009, 09:30:37) Sys(Linux i686 2.6.28-14-generic)
Startup: Tue, 25 Aug 2009 15:30:44 -0500   Running: 2 days 21:33:32
;
</PRE>
</CODE></BLOCKQUOTE>
<P>The 
<A HREF="#gkstatusauth">GkStatus::Auth</A> section contains additional information on securing the status port.
<P>
<H2>3.3 Running the gatekeeper in routed mode</H2>

<P>Starting the gatekeeper in routed mode means that the gatekeeper
uses "gatekeeper routed signaling". 
All signaling messages go through the gatekeeper, giving it
much greater control over the calls.
<P>Start GnuGk like this:
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > gnugk -r
</PRE>
</CODE></BLOCKQUOTE>
<P>will put the gatekeeper in routed mode. Telnet to the status port
and make a call to see what messages are now handled by the gatekeeper.
<P>Note that all media packets (audio and video) are still sent
directly between the endpoints (the 2 instances of ohphone).
<P>
<H2>3.4 A virtual PBX: Disconnecting calls</H2>

<P>Until now the gatekeeper has acted only as a mechanism
to resolve symbolic names to IP addresses. This is a critical function of
a gatekeeper, but the gatekeeper is capable of much more.
<P>Because the gatekeeper has a lot of control over the calls,
it can also be used to terminate them. While
connected to the status port, you can list all active calls
with "<CODE>PrintCurrentCalls</CODE>". To terminate a call, type
"<CODE>Disconnectip 1.2.3.4</CODE>" for one of the endpoints.
<P>For example, a simple script could be written to connect to
the status port, obtain a list of ongoing calls and terminate
them after 5 minutes to prevent users from using too many system resources.
<P>Other functions such as TransferCall are also available.
<P>
<H2>3.5 Routing calls to a gateway to reach external users</H2>

<P>Without using a gateway you can only call other people with an
IP phone over the Internet. To reach people with ordinary telephones
you must use a gateway.
<P>
<BLOCKQUOTE><CODE>
<PRE>
_________________          ______________
| endpoint "jan"|          |            |
| 192.168.88.35 |--------->| Gatekeeper |
|_______________|          |            |
_________________          |            |
| gateway "gw1" | outgoing |            |
| 192.168.88.37 |&lt;---------|____________|
|_______________|
</PRE>
</CODE></BLOCKQUOTE>
<P>The gatekeeper must be configured to specify which calls should be routed
to the gateway and which numbers can be called directly.
Use the [RasSrv::GWPrefixes] section of the config file to tell
the gatekeeper the prefix of numbers that should be routed to the
gateway.
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
gw1=0
</PRE>
</CODE></BLOCKQUOTE>
<P>This entry tells the gatekeeper to route all calls to E.164 numbers
starting with "0" to the gateway that has registered with the H.323
alias "gw1". If there is no registered gateway with that alias the
call will fail. 
<P><B>NOTE:</B> You must use the gateway alias - you cannot use the IP address of the gateway.
<P>A prefix can contain digits <CODE>0-9</CODE>, <CODE>#</CODE> and <CODE>*</CODE>. It can also
contain a special character <CODE>.</CODE> (a dot) that matches any digit
and can be prefixed with <CODE>!</CODE> (an exclamation mark) to disable the prefix.
Prefix matching is done according to the longest matching prefix rule,
with ! rules having higher priority if lengths are equal. You may also 
use := syntax to set the priority between several gateways matching the same prefix (see section 
<A HREF="#gwprefixes">[RasSrv::GWPrefixes]</A> for details). 
Some examples:
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
; This entry will route numbers starting with 0048 (but not with 004850 and 004860)
; to gw1
gw1=0048,!004850,!004860
; This entry will match only 001 with 10 digits following and route the call to
; gw2
gw2=001..........
</PRE>
</CODE></BLOCKQUOTE>
<P>
<P>
<H2>3.6 Rewriting E.164 numbers</H2>

<P>When using a gateway you often have to use different numbers internally
and rewrite them before sending them over a gateway into the telephone
network. You can use the 
<A HREF="#rewrite">RasSrv::RewriteE164</A>
section to configure that.
<P>Example:
You want to call number 12345 with your IP Phone and would like to
reach number 08765 behind a gateway called "gw1".
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
gw1=0

[RasSrv::RewriteE164]
12345=08765
</PRE>
</CODE></BLOCKQUOTE>
<P>You can also configure rewriting of E.164 numbers based on which gateway
you are receiving a call from or sending a call to using the
<A HREF="#gwrewrite">RasSrv::GWRewriteE164</A> section.
<P>Example:
You have two different gateways ("gw1" and "gw2") which you are sending
calls with prefix 0044 to, but which require a different prefix to be
added to the number after the routing has selected the gateway. This
might be for identification purposes for example.
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
gw1=0044
gw2=0044

[RasSrv::GWRewriteE164]
gw1=out=0044=77770044
gw2=out=0044=88880044
</PRE>
</CODE></BLOCKQUOTE>
<P>Example:
You want to identify calls from a particular gateway "gw1" with a specific
prefix before passing these calls to another gateway "gw2".
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
gw2=1

[RasSrv::GWRewriteE164]
gw1=in=00=123400
</PRE>
</CODE></BLOCKQUOTE>
<P>Rewrite expressions accept dot <CODE>'.'</CODE> and percent sign <CODE>'%'</CODE> wildcard
characters to allow building more general rules. The dot character can occur
on both the left and right hand sides of expressions. The percent sign can occur
only at the left side. Use <CODE>'.'</CODE> to match any character and copy it
to the rewritten string and <CODE>'%'</CODE> to match any character and skip it.
A few simple examples:
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::RewriteE164]
; Rewrite 0044 + min. 7 digits to 44 + min. 7 digits
0044.......=44.......
; Rewrite numbers starting with 11 + 4 digits + 11  to 22 + 4 digits + 22
; (like 11333311 => 22333322, 110000112345 => 220000222345)
11....11=22....22
; strip the first four digits from all numbers (11114858345 => 4858345)
; this is equivalent of 10 rules %%%%1=1, %%%%2=2, ... 
%%%%.=.
; insert two zeros in the middle of the number (111148581234 => 11110048581234)
....48=....0048
; even this is possible (415161 => 041051061)
4.5.6=04.05.06
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="s4">4. Basic Gatekeeper Configuration</A></H2>

<P>The behavior of the 
<A HREF="http://www.gnugk.org/">gatekeeper</A>
is determined by the command line
options and configuration file. Some command line options may override
a setting from the configuration file.
For example, the option <CODE>-l</CODE> overrides the setting <CODE>TimeToLive</CODE>
in the configuration file.
<P>
<H2><A NAME="commandline"></A> 4.1 Command Line Options</H2>

<P>Almost every option has a short and a long format, e.g.,
<CODE>-c</CODE> is the same as <CODE>--config</CODE>.
<P>
<H3>Basic</H3>

<P>
<DL>
<DT><B><CODE>-h  --help</CODE></B><DD><P>Show all available options and quit the program.
<DT><B><CODE>-c  --config filename</CODE></B><DD><P>Specify the configuration file to use.
<DT><B><CODE>-s  --section section</CODE></B><DD><P>Specify which main section to use in the configuration file. The default is [Gatekeeper::Main].
<DT><B><CODE>-i  --interface IP</CODE></B><DD><P>Specify the IP address that the gatekeeper listens to.
By default, the gatekeeper will automatically determine which IP address(es) it should use.  This
option will override the auto provisioning.
<DT><B><CODE>-l  --timetolive n</CODE></B><DD><P>Specify the time-to-live timer (in seconds) for endpoint registration.
Overrides the setting <CODE>TimeToLive</CODE> in the configuration file.
See 
<A HREF="#ttl">there</A> for detailed explanations.
<DT><B><CODE>-b  --bandwidth n</CODE></B><DD><P>Specify the total bandwidth available for the gatekeeper.
Without this option, bandwidth management
is disabled.
<DT><B><CODE>--pid filename</CODE></B><DD><P>Specify the pid file. Only valid for Unix version.
<DT><B><CODE>-u  --user name</CODE></B><DD><P>Run the gatekeeper process as this user. Only valid for Unix version.
<DT><B><CODE>--core n</CODE></B><DD><P>Enable writing core dump files when the application crashes. A core
dump file will not exceed n bytes in size. A special constant "unlimited"
may be used to not enforce any particular limit.  Only valid for Unix version.
</DL>
<P>
<H3>Gatekeeper Mode</H3>

<P>The options in this subsection override the settings in the
<A HREF="#routed">[RoutedMode] section</A> of the configuration file.
<DL>
<DT><B><CODE>-d  --direct</CODE></B><DD><P>Use direct endpoint call signaling.
<DT><B><CODE>-r  --routed</CODE></B><DD><P>Use gatekeeper routed call signaling.
<DT><B><CODE>-rr  --h245routed</CODE></B><DD><P>Use gatekeeper routed call signaling and H.245 control channel.
</DL>
<P>
<H3>Debug Information</H3>

<P>
<DL>
<DT><B><CODE>-o  --output filename</CODE></B><DD><P>Write trace log to the specified file.
<DT><B><CODE>-t  --trace</CODE></B><DD><P>Set trace verbosity. Each additional <CODE>-t</CODE> adds additional verbosity to the output.
For example, use <CODE>-ttttt</CODE> to set the trace level to 5.
</DL>
<P>
<H2><A NAME="config"></A> 4.2 Configuration File</H2>

<P>The 
<A HREF="http://www.gnugk.org/">GNU Gatekeeper</A>
configuration file is a standard text file. The basic format is:
<P>
<BLOCKQUOTE><CODE>
<PRE>
[Section String]
Key Name=Value String
</PRE>
</CODE></BLOCKQUOTE>
<P>Comments are marked with a hash (<CODE>#</CODE>) or a semicolon (<CODE>;</CODE>)
at the beginning of a line.
<P>The file
<CODE>complete.ini</CODE>
contains all available sections for GnuGk.
In most cases it doesn't make sense to use them all at once.
The file is just meant as a collection of examples for many settings.
<P>The configuration file can be changed at run time.
Once you modify the configuration file, you may issue the <CODE>reload</CODE> command
via the status port, or send the <CODE>HUP</CODE> signal to the gatekeeper process:
<BLOCKQUOTE><CODE>
<PRE>
kill -HUP `cat /var/run/gnugk.pid`
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="gkmain"></A> 4.3 Section [Gatekeeper::Main]</H2>

<P>
<UL>
<LI><CODE>Fortytwo=42</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>This setting is used to test for the presence of the config file. If it
is not found, a warning is issued.
Make sure it's in all your config files.
<P>
</LI>
<LI><CODE>Name=GnuGk</CODE><BR>
Default: <CODE>OpenH323GK</CODE><BR>
<P>Gatekeeper identifier of this gatekeeper. The gatekeeper will only respond to
GRQs for this ID and will use it in a number of messages to its endpoints.
<P>
</LI>
<LI><CODE>Home=192.168.1.1</CODE><BR>
Default: <CODE>0.0.0.0</CODE><BR>
<P>The gatekeeper will listen for requests on this IP address.
If set to <CODE>0.0.0.0</CODE> the gatekeeper will listen on all interfaces of your host.
Multiple Home addresses can be used
and must be separated with a semicolon (;) or comma (,).
<P>
</LI>
<LI><CODE>NetworkInterfaces=192.168.1.1/24,10.0.0.1/0</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Specify the network interfaces of the gatekeeper. By default the gatekeeper
will automatically detect the interfaces of your host, so this setting is not 
usually required, but is available if automatic detection fails. 
If you are using GnuGk behind a NAT box then you should use the ExternalIP
setting (described below) which will automatically configure GnuGk to operate as if it was
on the NAT box.  The ExternalIP setting will take precedence and will override this value.
<P><B>NOTE:</B> If this setting is changed, you must restart the gatekeeper.  A reload from the status port
will not cause this value to be re-read.
<P>
</LI>
<LI><CODE>Bind=192.168.1.1</CODE><BR>
Default: <CODE>0.0.0.0</CODE><BR>
<P>Specify the IP address for default routing. If there is only one interface then
this setting is ignored. Use this to specify which default IP address to use in a multihomed
virtual environment where there may be many virtual interfaces on one host.
<P>
</LI>
<LI><CODE>EndpointIDSuffix=_gk1</CODE><BR>
Default: <CODE>_endp</CODE><BR>
<P>The gatekeeper will assign a unique identifier to each registered endpoint.
This option can be used to specify a suffix to append to the endpoint identifier. This is only useful when using more than one gatekeeper.
<B>This setting doesn't change when the config is reloaded!</B>
<P>
</LI>
<LI>
<A NAME="ttl"></A> <CODE>TimeToLive=300</CODE><BR>
Default: <CODE>-1</CODE><BR>
<P>An endpoint's registration with a gatekeeper may have a limited life span.
The gatekeeper specifies the registration duration for an endpoint
by including a <B>timeToLive</B> field in the RCF message.
After the specified length of time, the registration is considered expired.
The endpoint must periodically send a RRQ having the <B>keepAlive</B>
bit set prior to the expiration time. Such a message may include a
minimum amount of information as described in H.225.0 and is known as a lightweight RRQ.
<P>The endpoint may request a shorter <B>timeToLive</B> in the RRQ message
to the gatekeeper.
<P>To avoid an overload of RRQ messages,
the gatekeeper automatically resets this timer
to 60 seconds if you specify a lower value.
<P>After the expiration time,
the gatekeeper will make two attempts using IRQ messages to determine
if the endpoint is still alive. If the endpoint responds with an IRR,
the registration will be extended. If not, the gatekeeper will send
a URQ with reason <B>ttlExpired</B> to the endpoint.
The endpoint must then re-register with the gatekeeper using a full RRQ message.
<P>To disable this feature, set it to <CODE>-1</CODE>.
<P>
</LI>
<LI><CODE>CompareAliasType=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>By default, a H323ID of '1234' won't match E164 number '1234' when comparing aliases. This parameter allows you 
to ignore the alias type when performing comparisons.
<P>
</LI>
<LI><CODE>CompareAliasCase=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>By default, alias 'jan' won't match alias 'Jan'.  If set to false, the comparison will not be case sensitive.
<P>
</LI>
<LI><CODE>TraceLevel=2</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Set trace level (same as -t on the command line).
<P><B>This setting doesn't change when the config is reloaded!</B>
<P>
</LI>
<LI><CODE>TotalBandwidth=100000</CODE><BR>
Default: <CODE>-1</CODE><BR>
<P>Total bandwidth available to be given to endpoints.
By default this feature is off.
<P><B>NOTE:</B>  At this time, the GnuGk only checks calls from registered endpoints and
many endpoints supply incorrect bandwidth values.
<P>
</LI>
<LI><CODE>RedirectGK=Endpoints > 100 | Calls > 50</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>This option allow you to redirect endpoints to alternate gatekeepers
if the gatekeeper becomes overloaded.
In the example above, the gatekeeper will
reject a RRQ if the number of registered endpoints would exceed 100,
or reject an ARQ if concurrent calls exceed 50.
<P>Furthermore, you may explicitly redirect all endpoints by
setting this option to <CODE>temporary</CODE> or <CODE>permanent</CODE>.
The gatekeeper will send a RAS rejection message with a list of
alternate gatekeepers defined in <CODE>AlternateGKs</CODE>.
Note that a <CODE>permanent</CODE> redirection means that the redirected endpoints
will not register with this gatekeeper again.
<B>NOTE:</B>  The redirect capability will only function with H.323 version 4
compliant endpoints.
<P>
</LI>
<LI><CODE>AlternateGKs=1.2.3.4:1719:false:120:GnuGk</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If the endpoint loses connectivity with GnuGk it should automatically try 
to register with the alternate gatekeeper specified here.
<P><B>NOTE:</B>  Depending on the endpoint, it may not attempt to re-establish a 
connection to its original gatekeeper.  Support for "Assigned Gatekeepers" was added
in H.323v6.  See 
<A HREF="http://www.packetizer.com/ipmc/h323/whatsnew_v6.html">http://www.packetizer.com/ipmc/h323/whatsnew_v6.html</A> for additional information.
<P>The primary gatekeeper includes a field in the RCF to inform endpoints which alternate
IP and gatekeeper identifier to use.
<P>The alternate gatekeeper needs to be aware of all 
registrations on the primary gatekeeper or else it would reject calls.
Our gatekeeper can forward every RRQ to an alternate IP address.
<P>The AlternateGKs config option specifies the fields contained in
the primary gatekeeper's RCF. The first and second fields of this string define
where (IP, port) to forward to.
The third tells endpoints whether they need to register with the alternate gatekeeper
before placing calls. They usually don't because we forward their RRQs, so they
are automatically known to the alternate gatekeeper.
The fourth field specifies the priority for this gatekeeper.
Lower is better; usually the primary gatekeeper is considered to have priority 1.
The last field specifies the alternate gatekeeper's identifier.
<P>You may specify multiple alternate gatekeepers as a comma separated list.
<P>
</LI>
<LI><CODE>SendTo=1.2.3.4:1719</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Although this information is contained in AlternateGKs, you must still
specify which address to forward RRQs to. This might differ from AlternateGK's
address due to multihomed systems, so it's a separate config option.
<P>You can specify multiple gatekeepers in a comma separated list.
<P>
</LI>
<LI><CODE>SkipForwards=1.2.3.4,5.6.7.8</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>To avoid circular forwarding, you shouldn't forward RRQs you get from the
other gatekeeper (this statement is true for both primary and alternate gatekeeper).
Two mechanisms are used to identify whether a request should be forwarded.
The first one looks for a flag in the RRQ. Since few endpoints implement this,
we can increase the overall reliability of the system by specifying it here.
<P>Specify the other gatekeeper's IP in this list.
<P>
</LI>
<LI><CODE>StatusPort=7000</CODE><BR>
Default: <CODE>7000</CODE><BR>
<P>Status port to monitor the gatekeeper.
See 
<A HREF="#monitor">this section</A> for details.
<P>
</LI>
<LI><CODE>StatusTraceLevel=2</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>Default output trace level for new status interface clients.
See 
<A HREF="#monitor">this section</A> for details.
<P>
</LI>
<LI><CODE>TimestampFormat=ISO8601</CODE><BR>
Default: <CODE>Cisco</CODE><BR>
<P>This setting configures the default format of timestamp strings generated by the gatekeeper.
This option affects 
<A HREF="#sqlacct">[SqlAcct]</A>, 
<A HREF="#radacct">[RadAcct]</A>, 
<A HREF="#fileacct">[FileAcct]</A>
and other modules, but not 
<A HREF="#calltable">[CallTable]</A>.
You can further customize timestamp formatting per module by configuring the
<CODE>TimestampFormat</CODE> setting in the module-specific configuration portion of the config file.
<P>There are four predefined formats:
<UL>
<LI><CODE>RFC822</CODE> - a default format used by the gatekeeper (example: Wed, 10 Nov 2004 16:02:01 +0100)</LI>
<LI><CODE>ISO8601</CODE> - standard ISO format (example: 2004-11-10 T 16:02:01 +0100)</LI>
<LI><CODE>Cisco</CODE> - format used by Cisco equipment (example: 16:02:01.534 CET Wed Nov 10 2004)</LI>
<LI><CODE>MySQL</CODE> - simple format that MySQL can understand (example: 2004-11-10 16:02:01)</LI>
</UL>
<P>If none of the predefined options is suitable, you can build your own format string using
rules from the <CODE>strftime</CODE> C function (see man strftime or search MSDN for strftime).
In general, the format string consists of regular character and format codes, preceded
by a percent sign. Example: "%Y-%m-%d and percent %%" will result in "2004-11-10 and percent %".
Some common format codes:
<UL>
<LI><CODE>%a</CODE> - abbreviated weekday name</LI>
<LI><CODE>%A</CODE> - full weekday name</LI>
<LI><CODE>%b</CODE> - abbreviated month name</LI>
<LI><CODE>%B</CODE> - full month name</LI>
<LI><CODE>%d</CODE> - day of month as decimal number</LI>
<LI><CODE>%H</CODE> - hour in 24-hour format</LI>
<LI><CODE>%I</CODE> - hour in 12-hour format</LI>
<LI><CODE>%m</CODE> - month as decimal number</LI>
<LI><CODE>%M</CODE> - minute as decimal number</LI>
<LI><CODE>%S</CODE> - second as decimal number</LI>
<LI><CODE>%y</CODE> - year without century</LI>
<LI><CODE>%Y</CODE> - year with century</LI>
<LI><CODE>%u</CODE> - microseconds as decimal number (<B>this is a GnuGk extension</B>)</LI>
<LI><CODE>%z</CODE> - time zone abbreviation (+0100)</LI>
<LI><CODE>%Z</CODE> - time zone name</LI>
<LI><CODE>%%</CODE> - percent sign</LI>
</UL>
<P>
</LI>
<LI><CODE>EncryptAllPasswords=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Enable encryption of all passwords in the config (SQL passwords, RADIUS
passwords, [Password] passwords, [GkStatus::Auth] passwords). If enabled,
all passwords must be encrypted using the <CODE>addpasswd</CODE> utility. Otherwise
only [Password] and [GkStatus::Auth] passwords are encrypted (old behavior).
<P>
</LI>
<LI><CODE>KeyFilled=0</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a global padding byte to be used during password encryption/decryption. 
It can be overridden by setting <CODE>KeyFilled</CODE> within a particular config section.
Usually, you do not need to change this option.
<P>
</LI>
</UL>
<P>Most users will never need to change any of the following values.
They are mainly used for testing or very sophisticated applications.
<P>
<UL>
<LI><CODE>UseBroadcastListener=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Defines whether to listen to broadcast RAS requests. This requires
binding to all interfaces on a machine, so if you want to run multiple
gatekeepers on the same machine you should turn this off.
<P>
</LI>
<LI><CODE>UnicastRasPort=1719</CODE><BR>
Default: <CODE>1719</CODE><BR>
<P>The RAS channel TSAP identifier for unicast.
<P>
</LI>
<LI><CODE>UseMulticastListener=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Enable or disable gatekeeper discovery using multicast. By default it is enabled.
<P>
</LI>
<LI><CODE>MulticastPort=1718</CODE><BR>
Default: <CODE>1718</CODE><BR>
<P>The RAS channel TSAP identifier for multicast.
<P>
</LI>
<LI><CODE>MulticastGroup=224.0.1.41</CODE><BR>
Default: <CODE>224.0.1.41</CODE><BR>
<P>The multicast group for the RAS channel.
<P>
</LI>
<LI><CODE>EndpointSignalPort=1720</CODE><BR>
Default: <CODE>1720</CODE><BR>
<P>Default port for call signaling channel of endpoints.
<P>
</LI>
<LI><CODE>ListenQueueLength=1024</CODE><BR>
Default: <CODE>1024</CODE><BR>
<P>Queue length for incoming TCP connection.
<P>
</LI>
<LI><CODE>SignalReadTimeout=1000</CODE><BR>
Default: <CODE>1000</CODE><BR>
<P>Time in milliseconds for read timeout on call signaling channels (Q931).
<P>
</LI>
<LI><CODE>StatusReadTimeout=3000</CODE><BR>
Default: <CODE>3000</CODE><BR>
<P>Time in milliseconds for read timeout on status channel.
<P>
</LI>
<LI><CODE>StatusWriteTimeout=5000</CODE><BR>
Default: <CODE>5000</CODE><BR>
<P>Time in milliseconds for write timeout on status channel.
<P>
</LI>
<LI><CODE>ExternalIP=myip.no-ip.com</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>When using GnuGk behind a NAT you can set the external IP address 
that you wish the gatekeeper to masquerade as. This will allow external endpoints
and other gatekeepers to contact the NATed gatekeeper. To work you must port
forward the required ports to the gatekeeper IP or put the gatekeeper in the NAT box
DMZ. This is different than the bind setting, which specifies a physical IP
address on the GnuGk box.  
<P>You may specify an IP address or a fully-qualified domain name (FQDN).  If
you use a FQDN and <CODE>ExternalIsDynamic</CODE> is set to false, it will be
resolved to an IP address on startup or configuration reload.  If
<CODE>ExternalIsDynamic</CODE> is set to true, the name will be stored and
resolved when needed.
<P>
</LI>
<LI><CODE>ExternalIsDynamic=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Configures the GnuGk to support an external dynamic address.  If enabled,
GnuGk will ensure that the Dynamic DNS (DDNS) service receives keep-alive
messages to maintain your DDNS name lease.  You must also configure the
<CODE>ExternalIP</CODE> setting with a DNS address maintained by a DDNS service
such as www.dyndns.com or www.no-ip.com.
<P>
</LI>
<LI><CODE>DefaultDomain=gnugk.org,gnugk.de</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If the GnuGk receives a request for an address in the format
<B>user@domain.com</B>, this option will strip the domain from the address
if it matches the <CODE>DefaultDomain</CODE> setting and will then process the
request using just the "<B>user</B>" field.  This is useful when receiving
interdomain calls placed via SRV routing policy where the full URI is
received.  It can also be used in conjunction with the
[RasSrv::RewriteAlias] section to convert the received URI into a E164
number for further processing and routing. 
<P>
</LI>
<LI><CODE>Authenticators=H.235.1,CAT</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Selects the specific authenticators to use when authenticating endpoints. 
The default options are: H.235.1 (HMAC SHA1 /  old H235AnnexD), MD5 (Digest Authentication) and CAT (Cisco Access Tokens ie RADIUS). 
If this setting is omitted, all authenticators are loaded by default. 
If you are using plugin authenticators, then you may want to disable the default authenticators to provide optimum security.
Note: H.235.1 requires OpenSSL support compiled into GnuGk.
<B>This switch is only available if GnuGk is compiled with H323Plus.</B>
<P>
</LI>
<LI><CODE>DisconnectCallsOnShutdown=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>GnuGk will disconnect all ongoing calls when it shuts down and
will send an unregistration request to all endpoints.
To override this default, set this parameter to "0".
This switch is intended mainly for gatekeepers running in direct mode;
in routed mode and proxy mode calls will still get disrupted when the gatekeeper shuts down.
<P>
</LI>
</UL>
<P>
<P>
<H2><A NAME="gkstatusauth"></A> 4.4 Section [GkStatus::Auth]</H2>

<P>Defines a number of rules regarding who is allowed to connect to the status port.
Access to the status port provides full control over your gatekeeper. Ensure that this is set correctly.
<UL>
<LI><CODE>rule=allow</CODE><BR>
Default: <CODE>forbid</CODE><BR>
<P>Possible values are
<UL>
<LI><CODE>forbid</CODE> - disallow any connection.</LI>
<LI><CODE>allow</CODE> - allow any connection</LI>
<LI><CODE>explicit</CODE> - reads the parameter <CODE>ip=value</CODE>
where <CODE>ip</CODE> is the IP address of the client,
<CODE>value</CODE> is <CODE>1,0</CODE> or <CODE>allow,forbid</CODE> or <CODE>yes,no</CODE>.
If <CODE>ip</CODE> is not listed the parameter <CODE>default</CODE> is used.</LI>
<LI><CODE>regex</CODE> - the IP of the client is matched against the given regular expression.
<P>
<DL>
<DT><B>Example:</B><DD><P>To allow client from 195.71.129.0/24 and 195.71.131.0/24:
<BLOCKQUOTE>
<CODE>regex=^195\.71\.(129|131)\.[0-9]+$</CODE>
</BLOCKQUOTE>
</DL>
</LI>
<LI><CODE>password</CODE> - the user must provide an appropriate username and password to login. The format of username/password is the same as 
<A HREF="#password">[SimplePasswordAuth]</A> section.
</LI>
</UL>
<P>These rules may be combined with "|" (to specify a logical "OR") or "&amp;" (for logical "AND"). For example,
<UL>
<LI><CODE>rule=explicit | regex</CODE><BR>
The IP of the client must match <CODE>explicit</CODE> <B>or</B> <CODE>regex</CODE> rule.
<P>
</LI>
<LI><CODE>rule=regex &amp; password</CODE><BR>
The IP of the client must match <CODE>regex</CODE> rule, <B>and</B> the user has to login by username and password.</LI>
</UL>
<P>
</LI>
<LI><CODE>default=allow</CODE><BR>
Default: <CODE>forbid</CODE><BR>
<P>Only used when <CODE>rule=explicit</CODE>.
<P>
</LI>
<LI><CODE>Shutdown=forbid</CODE><BR>
Default: <CODE>allow</CODE><BR>
<P>To allow the gatekeeper to be shutdown via status port.
<P>
</LI>
<LI><CODE>DelayReject=5</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Time (in seconds) to wait before rejecting an invalid username/password.  Useful to insert
a delay in brute-force attacks.
</LI>
</UL>
<P>
<H2><A NAME="gkstatusfilteringsect"></A> 4.5 Section [GkStatus::Filtering]</H2>

<P>See 
<A HREF="#statusportfiltering">Status Port Filtering</A>.
<P>
<H2><A NAME="logfile"></A> 4.6 Section [LogFile]</H2>

<P>This section defines log file related parameters. Currently, it allows
users to specify log file rotation options.
<P>
<UL>
<LI><CODE>Filename=/var/log/gk_trace.log</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Set the output filename for the log file (same as -o on the command line).
On Windows, backslashes in the file name have to be escaped.
<P><B>This setting doesn't change when the config is reloaded!</B>
<P>
</LI>
<LI><CODE>Rotate=Hourly | Daily | Weekly | Monthly</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If set, the log file will be rotated based on this setting. Hourly rotation
enables rotation once per hour, daily - once per day, weekly - once per week
and monthly - once per month. An exact rotation moment is determined by a combination
of <CODE>RotateDay</CODE> and <CODE>RotateTime</CODE> variables. During rotation, an existing 
file is renamed to CURRENT_FILENAME.YYYYMMDD-HHMMSS, where YYYYMMDD-HHMMSS 
is replaced with the current timestamp, and new lines are logged to an empty 
file. To disable rotation, do not configure the <CODE>Rotate</CODE> parameter or set it to 0.
<P>
<DL>
<DT><B>Example 1 - rotate every hour (00:45, 01:45, ..., 23:45):</B><DD><P><CODE>[LogFile]</CODE><BR>
<CODE>Rotate=Hourly</CODE><BR>
<CODE>RotateTime=45</CODE><BR>
<CODE>Filename=/var/log/gk_trace.log</CODE><BR>
</DL>
<P>
<DL>
<DT><B>Example 2 - rotate every day at 23:00 (11PM):</B><DD><P><CODE>[LogFile]</CODE><BR>
<CODE>Rotate=Daily</CODE><BR>
<CODE>RotateTime=23:00</CODE><BR>
<CODE>Filename=C:\\Logs\\GnuGk.log</CODE><BR>
</DL>
<P>
<DL>
<DT><B>Example 3 - rotate every Sunday at 00:59:</B><DD><P><CODE>[LogFile]</CODE><BR>
<CODE>Rotate=Weekly</CODE><BR>
<CODE>RotateDay=Sun</CODE><BR>
<CODE>RotateTime=00:59</CODE><BR>
</DL>
<P>
<DL>
<DT><B>Example 4 - rotate on the last day of each month:</B><DD><P><CODE>[LogFile]</CODE><BR>
<CODE>Rotate=Monthly</CODE><BR>
<CODE>RotateDay=31</CODE><BR>
<CODE>RotateTime=23:00</CODE><BR>
</DL>
</LI>
</UL>
<P>
<H2><A NAME="s5">5. Routed Mode and Proxy Configuration</A></H2>

<H2><A NAME="routed"></A> 5.1 Section [RoutedMode]</H2>

<P>Call signaling messages may be passed in two ways:
The first method is Direct Endpoint Call Signaling, where 
call signaling messages are passed directly between the endpoints.
The second method is Gatekeeper Routed Call Signaling. With this method,
the call signaling messages are routed through the gatekeeper.
<P>When Gatekeeper Routed call signaling is used, there are three different options for routing
of the H.245 control channel and media channels.
<P>
<DL>
<DT><B>Case I.</B><DD><P>The gatekeeper doesn't route them.
The H.245 control channel and media channels are established directly
between the endpoints.
<DT><B>Case II.</B><DD><P>The H.245 control channel is routed through the gatekeeper, while the media channels
are established directly between the endpoints.
<DT><B>Case III.</B><DD><P>The gatekeeper routes the H.245 control channel,
as well as all media channels, including RTP/RTCP for audio and video,
and T.120 channel for data. In this case, no traffic is passed
directly between the endpoints. This is usually called a H.323 Proxy,
and can be treated as a H.323-H.323 gateway.
</DL>
<P>This section defines the gatekeeper routed mode options (case I &amp; II).
The proxy feature is defined in the 
<A HREF="#proxy">next section</A>.
<P>The settings in this section may be updated by reloading the configuration while the gatekeeper is running.
<P>
<UL>
<LI><CODE>GKRouted=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Enables gatekeeper routed signaling mode.
<P>
</LI>
<LI><CODE>H245Routed=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Enables routing of the H.245 control channel through the gatekeeper.
This setting is honored if <CODE>GKRouted=1</CODE> and H.245 tunneling is disabled
for a call. Even when this option is disabled, if Proxy or ProxyForNAT
takes effect, a H.245 channel is always routed through the gatekeeper
for calls being proxied.
<P>
</LI>
<LI><CODE>CallSignalPort=1720</CODE><BR>
Default: <CODE>1721</CODE><BR>
<P>The port for call signaling on the gatekeeper.
The default port is <CODE>1721</CODE>. We don't use the well-known port <CODE>1720</CODE> by default
so you can run an H.323 endpoint or gateway in the same machine as the gatekeeper.
You may set it to <CODE>0</CODE> to let the gatekeeper choose an arbitrary port.
<P>
</LI>
<LI><CODE>CallSignalHandlerNumber=10</CODE><BR>
Default: <CODE>5</CODE><BR>
<P>The number of threads dedicated to handle signaling/H.245 channels (between 1-200).
You may increase this number in a heavy loaded gatekeeper. Each thread
can process one signaling message at time, so increasing this number
will increase call throughput. Under Windows, there exists a default limit
of 64 sockets used by a single signaling thread, so each signaling thread
is able to handle at most 32 calls (with H.245 tunneling enabled).
<P>
</LI>
<LI><CODE>RtpHandlerNumber=2</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>The number of RTP proxy handling threads. Increase this value only if you
experience problems with RTP delay or jitter on a heavily loaded gatekeeper.
Special care has to be taken on Windows, as RTP handling threads are subject
to the same limit of 64 sockets as signaling threads. Each RTP thread is
able to handle at most 32 proxied calls (2 sockets per call).
<P>
</LI>
<LI><CODE>AcceptNeighborsCalls=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>With this feature enabled, the call signaling thread will accept calls
without a pre-existing CallRec found in the CallTable, provided an endpoint
corresponding to the destinationAddress in Setup can be found in the
RegistrationTable, and the calling party is a neighbor or parent gatekeeper.
The gatekeeper will also use its own call signaling address in the LCF
when responding to the LRQ. Call signaling will be routed
to gatekeeper 2 in gatekeeper-to-gatekeeper calls.
As a result, the CDRs in gatekeeper 2 will correctly show the connected
time, instead of 'unconnected'.
<P>
</LI>
<LI><CODE>AcceptUnregisteredCalls=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>With this feature enabled, the gatekeeper will accept calls
from any unregistered endpoint.
Make sure you do proper authentication on these calls if you
don't want to let everybody use your gatekeeper.
When working with unregistered endpoints, you will probably also want
to change the CallSignalPort to 1720.
<P>
</LI>
<LI><CODE>RemoveH245AddressOnTunneling=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Some endpoints send h245Address in the UUIE of Q.931 even when h245Tunneling
is set to TRUE. This may cause interoperability problems. If the option
is TRUE, the gatekeeper will remove h245Address when h245Tunneling flag
is TRUE. This enforces the remote party to stay in tunneling mode.
<P>
</LI>
<LI><CODE>RemoveCallOnDRQ=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>With this option disabled, the gatekeeper will not disconnect a call
if it receives a DRQ for it. This avoids potential race conditions when
a DRQ overtakes a Release Complete.
This is only meaningful in routed mode because in direct mode, the only
mechanism to signal end-of-call is a DRQ.
When using call failover this must be set to 0.
<P>
</LI>
<LI><CODE>DropCallsByReleaseComplete=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>According to Recommendation H.323, the gatekeeper could tear down a call
by sending RAS DisengageRequest to endpoints.
However, some bad endpoints just ignore this command.
With this option turning on, the gatekeeper will send Q.931
Release Complete instead of RAS DRQ to both endpoints to force them
drop the call.
<P>
</LI>
<LI><CODE>SendReleaseCompleteOnDRQ=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>On hangup, the endpoint sends both Release Complete within H.225/Q.931 and
DRQ within RAS. It may happen that DRQ is processed first, causing the
gatekeeper to close the call signaling channel, thus preventing the
Release Complete from being forwarding to the other endpoint.
Though the gatekeeper closes the TCP channel to the destination,
some endpoints (e.g. Cisco CallManager) don't drop the call even if
the call signaling channel is closed.
This results in phones that keep ringing if the caller hangs up
before the called number answers.
Setting this parameter to <CODE>1</CODE> makes the gatekeeper always send
Release Complete to both endpoints before closing the call when
it receives a DRQ from one of the parties.
<P>
</LI>
<LI><CODE>SupportNATedEndpoints=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Whether to allow an endpoint behind a NAT box register to the gatekeeper.
If yes, the gatekeeper will translate the IP address in Q.931 and H.245
channel into the IP of NAT box.
<P>GnuGk supports NAT outbound calls (from an endpoint behind NAT
to public networks) directly without any necessary modification
of endpoints or NAT box. Just register the endpoint with GnuGk
and you can make call now. 
<P>
</LI>
<LI><CODE>SupportCallingNATedEndpoints=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Whether to allow an endpoint behind an NAT box that support GnuGk NAT Traversal
technique to receive calls. Use this to block errant gateways that do not support
GnuGk Nat Traversal technique properly from causing one way audio problems when 
trying to call to the gateway. Calls to the gateways return caller unreachable.
To be effective SupportNATedEndpoints must be set to 1.
<P>
</LI>
<LI><CODE>TreatUnregisteredNAT=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Used in conjunction with AcceptUnregisteredCalls and SupportNATedEndpoints will
automatically treat all unregistered calls which cannot be determined as
being NAT are treated as being NAT. 
<P>Not all Endpoints send sourceSignalAddress in the setup message which can
be used to determine whether a caller is NAT. This adds support to those that 
don't.
<P>
</LI>
<LI><CODE>ScreenDisplayIE=MyID</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Modify the DisplayIE of Q.931 to the specified value.
<P>
</LI>
<LI><CODE>ScreenCallingPartyNumberIE=0965123456</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Modify the CallingPartyNumberIE of Q.931 to the specified value.
<P>
</LI>
<LI><CODE>ScreenSourceAddress=MyID</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Modify the sourceAddress field of UUIE element from Q.931 Setup message.
<P>
</LI>
<LI><CODE>ForwardOnFacility=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>If yes, on receiving Q.931 Facility with reason <B>callForwarded</B>, <B>routeCallToGatekeeper</B> or <B>routeCallToMC</B>,
the gatekeeper will forwards call Setup directly to the forwarded endpoint,
instead of passing the message back to the caller.
If you have broken endpoints that can't handle Q.931 Facility with reason
<B>callForwarded</B> (or the other reasons), turn on this option. Note that this feature
may not always work correctly, as it does not provide any means
of capability renegotiation and media channel reopening.
The call is only forwarded if the forwarder is the called party and
the H.245 channel is not established, yet.
<P>
</LI>
<LI><CODE>ShowForwarderNumber=0</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Whether to rewrite the calling party number to the number of forwarder.
It's usually used for billing purpose.
Only valid if <CODE>ForwardOnFacility=1</CODE>.
<P>
</LI>
<LI><CODE>Q931PortRange=20000-20999</CODE><BR>
Default: <CODE>N/A (let the OS allocate ports)</CODE><BR>
<P>Specify the range of TCP port number for Q.931 signaling channels.
Note the range size may limit the number of concurrent calls.
Make sure this range is wide enough to take into account TIME_WAIT
TCP socket timeout before a socket can be reused after closed.
TIME_WAIT may vary from 15 seconds to a few minutes, depending on an OS.
So if for example your range is 2000-2001 and you made two calls, the next two calls can be
made after TIME_WAIT timeout elapses and the sockets can be reused.
The same applies to <CODE>H245PortRange</CODE> and <CODE>T120PortRange</CODE>. TIME_WAIT
can be usually tuned down on most OSes.
<P>
</LI>
<LI><CODE>H245PortRange=30000-30999</CODE><BR>
Default: <CODE>N/A (let the OS allocate ports)</CODE><BR>
<P>Specify the range of TCP port number for H.245 control channels.
Note the range size may limit the number of concurrent calls.
See remarks about TIME_WAIT socket state timeout in the <CODE>Q931PortRange</CODE>
description.
<P>
</LI>
<LI><CODE>SetupTimeout=4000</CODE><BR>
Default: <CODE>8000</CODE><BR>
<P>A timeout value (in milliseconds) to wait for a first message (Setup)
to be received after a signaling TCP channel has been opened.
<P>
</LI>
<LI><CODE>SignalTimeout=10000</CODE><BR>
Default: <CODE>30000</CODE><BR>
<P>A timeout value (in milliseconds) to wait for a signaling channel
to be opened after an ACF message is sent or to wait for an Alerting
message after a signaling channel has been opened. This option
can be thought as a maximum allowed PDD (Post Dial Delay) value.
<P>
</LI>
<LI><CODE>AlertingTimeout=60000</CODE><BR>
Default: <CODE>180000</CODE><BR>
<P>A timeout value (in milliseconds) to wait for a Connect message
after a call entered Alerting state. This option can be thought
as a maximum "ringing time".
<P>
</LI>
<LI><CODE>TcpKeepAlive=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Enable/disable keepalive feature on TCP signaling sockets. This can
help to detect inactive signaling channels and prevent dead calls from hanging
in the call table. For this option to work, you also need to tweak system
settings to adjust keep alive timeout. See docs/keepalive.txt for more details.
<P>
</LI>
<LI><CODE>TranslateFacility=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Enable this option if you have interoperability problems between H.323v4
and non-H.323v4 endpoints. It converts Facility messages with reason = transportedInformation
into Facility messages with an empty body, because some endpoints do not
process tunneled H.245 messages inside Facility, if the body is not empty.
The conversion is performed only when necessary - if both endpoints are v4
or both endpoints are pre-v4, nothing is changed.
<P>
</LI>
<LI><CODE>SocketCleanupTimeout=1000</CODE><BR>
Default: <CODE>5000</CODE><BR>
<P>Define time to wait before an unused socket is closed (if it is not yet closed)
and deleted (its memory is released). If you use very small port ranges, like 
a few ports (e.g. RTPPortRange=2000-2009), you may want to decrease this value
to get sockets reusable faster.
<P>
</LI>
<LI><CODE>ActivateFailover=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Activate call failover: When activated, GnuGk will try to find
other possible routes to a destination if the call fails on the
first route. The list of routes for a call is built when the call
first comes in and currently not all routing policies are able to
provide multiple routes.
You can use the 'internal' and the 'sql' policy to provide multiple routes.
In addition to that multiple routes can be set by SQL and Radius authenticators.
<P>For accounting of calls using failover, see the SingleFailoverCDR
switch in the 
<A HREF="#calltable">[CallTable]</A> section.
<P>
</LI>
<LI><CODE>FailoverCauses=1-15,21-127</CODE><BR>
Default: <CODE>1-15,21-127</CODE><BR>
<P>Define which cause codes in a ReleaseComplete will trigger
call failover.
<P>
</LI>
<LI><CODE>DisableRetryChecks=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>This will disable all checks if a failed call has already received
FastStart or H.245 messages. Caution: Using this switch enables you
to retry more calls, but you run the risk that some of the retried
calls will fail because the caller is already in a state where he
can't talk to a new partner.
<P>
</LI>
<LI><CODE>CalledTypeOfNumber=1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets Called-Party-Number type of number to the specified value
for all calls
(0 - UnknownType, 1 - InternationalType, 2 - NationalType,
3 - NetworkSpecificType, 4 - SubscriberType, 6 - AbbreviatedType, 7 - ReservedType).
<P>
</LI>
<LI><CODE>CallingTypeOfNumber=1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets Calling-Party-Number type of number to the specified value
for all calls
(0 - UnknownType, 1 - InternationalType, 2 - NationalType,
3 - NetworkSpecificType, 4 - SubscriberType, 6 - AbbreviatedType, 7 - ReservedType).
<P>
</LI>
<LI><CODE>CalledPlanOfNumber=1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets Called-Numbering-Plan of number to the specified value
(0 - UnknownType, 1 - ISDN, 3 - X.121 numbering, 4 - Telex, 8 - National standard, 9 - private numbering).
<P>
</LI>
<LI><CODE>CallingPlanOfNumber=1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets Calling-Numbering-Plan of number to the specified value
(0 - UnknownType, 1 - ISDN, 3 - X.121 numbering, 4 - Telex, 8 - National standard, 9 - private numbering).
<P>
</LI>
<LI><CODE>ENUMservers=e164.org,e164.arpa</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets the enum server list in priority order separated by (,) for the enum policy. 
This overrides the PWLIB_ENUM_PATH environmental variable.
<P>
</LI>
<LI><CODE>RDSservers=myvirtualhost.com</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Use this to set RDS server to query for rds routing policy. 
This set the domains to use to resolve URI's which do not have SRV records and 
maybe virtually hosted or SRV records are stored in another host.
This overrides the PWLIB_RDS_PATH environmental variable.
<P>
</LI>
<LI><CODE>CpsLimit=10</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Limit the rate of incoming calls to n calls per second. If more calls are received they are
rejected on TCP level without H.323 error messages and they won't show up in CDRs.
A value of zero (default) disables the feature.
<P>The limit only applies if the calls in the check interval are greater than check-interval * CPS-rate. This allows small call spikes on a machine without much load, but will apply strict limits when the overall load is high.
<P>This feature is meant to shield the gatekeeper from overload and to avoid as much resource usage a possible in an overload situation.
<P>Currently the calls are blocked when the first message comes in on the signaling port. This makes it
very effective for unregistered calls. But so far ARQs are not blocked, so it will be less effective with
registered calls.
<P>
</LI>
<LI><CODE>CpsCheckInterval=1</CODE><BR>
Default: <CODE>5</CODE><BR>
<P>Define the check interval in seconds before the CpsLimit is applied.
<P>
</LI>
<LI><CODE>GenerateCallProceeding=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>When set, GnuGk will generate a CallProceeding for each Setup message it receives.
This can be helpful to avoid a timeout in calling endpoints if the destination takes
a long time to answer or the call is processed in a virtual queue. Without setting
UseProvisionalRespToH245Tunneling=1 this will disable H.245 tunneling.
<P>CallProceeding messages sent by endpoints or gateways will be translated into Facility
or Progress messages.
<P>
</LI>
<LI><CODE>UseProvisionalRespToH245Tunneling=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>WARNING: This is an experimental feature and not tested very well.
<P>If you only use H.323 equipment that supports provisionalRespToH245Tunneling,
you can set this switch to keep H.245 tunneling enabled when using gatekeeper
generated CallProceeding.
<P>
</LI>
<LI><CODE>EnableH450.2=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>When set, GnuGk will intercept H.450.2 call transfer messages and if possible transfer 
the call on behalf of the endpoint. This allows the endpoint initiated transferring of
calls where the remote endpoint may not support H.450 and the gatekeeper initiates the 
call transfer.  
<P>
</LI>
<LI><CODE>TranslateReceivedQ931Cause=17:=34</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Translate all received cause codes in ReleaseComplete messages.
In the above example code 17 (User busy) will be translated into cause code 34 (No circuit/channel available).
<P>
</LI>
<LI><CODE>TranslateSentQ931Cause=21:=34,27:=34</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Translate all cause codes in ReleaseComplete messages sent out.
In the above example code 21 and 27 will be translated into cause code 34, because this particular gateway might deal with error code 34 better than with others.
<P>
</LI>
<LI><CODE>RemoveH235Call=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>For compatibility with endpoints which do not support large Setup messages,
this switch removes tokens and cryptoTokens from Setups to make them smaller.
<P>
</LI>
<LI><CODE>RemoveH460Call=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>For compatibility with pre-H323v4 devices that do not support H.460,
this switch strips the H.460 feature advertisements from the Setup PDU.
Usually they should be ignored anyway; use this switch if they cause trouble.
<P>
</LI>
<LI><CODE>ForceNATKeepAlive=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Force ALL registrations to use a keepAlive TCP socket.
<P>
</LI>
<LI><CODE>EnableH46018=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Enable support for H.460.18 and H.460.19. This feature is covered by patents held by Tandberg.
If you don't use the official releases by the GNU Gatekeeper Project, make sure you have a
valid license before enabling it.
<P>
</LI>
<LI><CODE>H46018NoNat=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Enable H.460.18 if the endpoint is not behind a NAT. Setting to 0 will 
disable H.460.18 if the endpoint is detected as not being behind a NAT. If H.460.23 is supported
and enabled then direct media is still supported.
<P>
</LI>
<LI><CODE>EnableH46023=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Enable support for H.460.23/.24
<P>
</LI>
<LI><CODE>H46023STUN=stun.ekiga.net,192.168.1.10</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets the STUN server list for use with H.460.23 separated by (,). 
Each Network interface must have a STUNserver set for H.460.23 support on that interface.
<P>
</LI>
<LI><CODE>NATStdMin=18</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Require registering endpoints detected as being behind a NAT to support a Standard NAT Traversal mechanism.
When an endpoint registers from behind a NAT and does not support the minimum NAT standard then the registration
will be rejected with a reason neededFeatureNotSupported.
Valid values are "18" for H.460.18/.19 and "23" for H.460.23/.24
<P>
</LI>
<LI><CODE>TranslateSorensonSourceInfo=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Translate the non-standard caller information from a Sorenson VP200 into sourceAddress and CallingPartyIE.
<P>
</LI>
<LI><CODE>RemoveFaxUDPOptionsFromRM=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Avaya Communication Manager 3.1 equipped by TN2602AP media processor becomes confused
when it receives t38FaxUdpOptions in t38FaxProfile of H.245 RequestMode. For example,
AddPac VoiceFinder does so. After that TN2602AP starts to send larger T.38 packets than
receiver can process. This results in facsimile document distortion. So we need to remove
t38FaxUdpOptions from RM to make ACM3.1+TN2602AP become compatible with endpoints which send
t38FaxUdpOptions in RM.
<P>
</LI>
</UL>
<P>
<P>
<H2><A NAME="proxy"></A> 5.2 Section [Proxy]</H2>

<P>The section defines the H.323 proxy features. It means the gatekeeper will
route all the traffic between the calling and called endpoints, so there
is no traffic between the two endpoints directly. Thus it is very useful
if you have some endpoints using private IP behind an NAT box and some
endpoints using public IP outside the box.
<P>The gatekeeper can do proxy for logical channels of RTP/RTCP (audio and video)
and T.120 (data). Logical channels opened by fast-connect procedures
or H.245 tunneling are also supported.
<P>Note to make proxy work, the gatekeeper must have <B>direct connection</B>
to both networks of the caller and callee.
<P>
<UL>
<LI><CODE>Enable=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Whether to enable the proxy function. You have to enable gatekeeper
routed mode first (see the 
<A HREF="#routed">previous section</A>).
You don't have to specify H.245 routed.
It will automatically be used if required.
<P>
</LI>
<LI><CODE>InternalNetwork=10.0.1.0/24</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If you want to override automatic detection of networks behind the proxy, you may do so by specifying them here.
Multiple internal networks are allowed.
Packets to internal networks will use the local interface as sender instead of the default IP or ExternalIP.
For internal networks, the proxying can be disabled, even when global proxying is activated.
<P>
<DL>
<DT><B>Format:</B><DD><P><CODE>InternalNetwork=network address/netmask[,network address/netmask,...]</CODE>
<P>The netmask can be expressed in decimal dot notation or
CIDR notation (prefix length), as shown in the example.
<DT><B>Example:</B><DD><P><CODE>InternalNetwork=10.0.0.0/255.0.0.0,192.168.0.0/24</CODE>
</DL>
<P>
</LI>
<LI><CODE>ProxyAlways=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Always proxy all calls regardless of other settings.
<P>
</LI>
<LI><CODE>T120PortRange=40000-40999</CODE><BR>
Default: <CODE>N/A (let the OS allocate ports)</CODE><BR>
<P>Specify the range of TCP port number for T.120 data channels.
Note the range size may limit the number of concurrent calls.
See remarks about TIME_WAIT socket state timeout in the <CODE>Q931PortRange</CODE>
description.
<P>
</LI>
<LI><CODE>RTPPortRange=50000-59999</CODE><BR>
Default: <CODE>1024-65535</CODE><BR>
<P>Specify the range of UDP port number for RTP/RTCP channels. Since RTP streams require two sockets, the range must contain an even number of ports.
Note that the size of the specified range may limit the number of possible concurrent calls.
<P>
</LI>
<LI><CODE>ProxyForNAT=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>If set, the gatekeeper will function as a proxy for calls where one of the participating endpoints
is behind a NAT box. This ensures the RTP/RTCP stream can
penetrate into the NAT box without modifying it.
However, the endpoint behind the NAT box must use the same port
to send and receive RTP/RTCP stream.
If you have bad or broken endpoints that don't satisfy the precondition,
you should disable this feature and let the NAT box forward
RTP/RTCP stream for you.
<P>
</LI>
<LI><CODE>ProxyForSameNAT=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Whether to proxy for calls between endpoints from the same NAT box.
There is a degree of uncertainty when endpoints are behind the same NAT as to 
whether they can communicate directly as one or both may be on subNATs. Disable
this feature with caution.
<P>
</LI>
<LI><CODE>DisableH235Call=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>This setting removes the cryptoTokens and clearTokens off the Setup message.
Use this when working with IP phones that do not support large Setup messages
<P>
</LI>
<LI><CODE>DisableH460Call=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>This setting removes the H.460 features from the Setup message. Use this with
pre-H.323v4 endpoints and gateways which cannot decode these messages.
<P>
</LI>
<LI><CODE>DisableRTPQueueing=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Sometimes GnuGk will receive RTP data before it knows where to forward it to.
By default GnuGk will queue this data up to a certain amount and send it once
the destination becomes available. In some cases this can cause a short loopback
of RTP data, so you might want to disable RTP queuing.
<P>
</LI>
<LI><CODE>EnableRTPMute=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>This setting allows either call party in media proxy mode to mute the 
audio/video by sending a * as either string or tone.userinput. The sending 
of * mutes the audio/video and a subsequent send of * unmutes the 
audio/video. Only the party who muted the call can unmute. This is designed 
as a hold function for terminals which do not support H450.4.
<P>
</LI>
<LI><CODE>RemoveMCInFastStartTransmitOffer=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Remove the mediaChannel from fastStart transmit offers.
For unicast transmit channels, mediaChannel should not be sent on offer;
it is responsibility of callee to provide mediaChannel in an answer.
<P>
</LI>
<LI><CODE>SearchBothSidesOnCLC=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>The H.245 CloseLogicalChannel request should only reference the
endpoint's own logical channels.
Some bad endpoint implementations require searching and closing
logical channels for the other endpoint as well.
Up to version 2.3.0 GnuGk did this automatically, but it can break
channel establishment in some cases, so now you have to set this
switch if you have these broken endpoints.
<P>
</LI>
</UL>
<P>
<P>
<H2><A NAME="modeselection"></A> 5.3 Section [ModeSelection]</H2>

<P>In routed mode or proxy mode, you can use this section to specify the exact routing mode
(routed mode, routed mode plus H.245 routing or proxy mode) by IP network.
<P>
<DL>
<DT><B>Syntax:</B><DD><P><CODE>network=mode[,mode]</CODE>
</DL>
<P>The network is specified by an IP plus optional CIDR, eg. 192.168.1.0/24.
The rule for the network with the longest netmask is used (the most specific).
<P>
<P>Possible modes are (the names are case in-sensitive)
<UL>
<LI><CODE>ROUTED</CODE><BR>
Routed mode where Q.931 messages are routed, but not H.245 messages (unless H.245 tunneling is active).</LI>
<LI><CODE>H245ROUTED</CODE><BR>
Routed mode plus H.245 routing.</LI>
<LI><CODE>PROXY</CODE><BR>
Proxy mode with RTP proxying.</LI>
</UL>
<P>The first mode is used for calls into and out of the specified network.
The second mode is used for calls that stay inside the network.
If only one mode is specified it is used for both cases.
<P>
<DL>
<DT><B>Example:</B><DD><P>In this example calls into and out of the 1.2.3.0/24 network are proxied, but calls that remain inside this network are in routed mode. Calls in the 3.4.5.0/24 are always proxied, even when they remain inside the network, unless IP 3.4.5.6 is involved. If 2 networks have a rule for the call, the one with the most proxying is used, eg. a call from 192.168.1.222 to 3.4.5.20 would be proxied.
<P>
<BLOCKQUOTE><CODE>
<PRE>
[ModeSelection]
127.0.0.0/24=ROUTED
192.168.0.0/18=H245ROUTED,ROUTED
1.2.3.0/24=PROXY,ROUTED
3.4.5.0/24=PROXY,PROXY
3.4.5.6=ROUTED
</PRE>
</CODE></BLOCKQUOTE>
<P>
</DL>
<P>If no rules matches the settings [RoutedMode]GkRouted=, H245Routed= or [Proxy]Enable= are used to determine the routing mode.
<P>There are a few cases where these rules don't apply, because
<A HREF="http://www.gnugk.org/">the GNU Gatekeeper</A>
knows that the call needs proxying:
For example calls involving H.460.18/.19 will always be proxied (because this protocol requires proxying).
<P>
<H2><A NAME="s6">6. Routing Configuration</A></H2>

<P>The following sections in the config file can be used to configure how calls are routed.
<P>Each call gets passed down a chain of routing policies.
Each policy may route the call and terminate the chain or modify it and
pass it on. You can use the setting in the following sections to
specify which policies to use and modify their behavior.
<P>
<H2><A NAME="routingpolicy"></A> 6.1 Section [RoutingPolicy]</H2>

<P>This section explains how the various potential routing
policies within the 
<A HREF="http://www.gnugk.org/">GNU Gatekeeper</A> work.
<P>The incoming call requests can be routed using the following
possibilities:
<P>
<UL>
<LI><CODE>explicit</CODE><BR>
<P>The destination is explicitly specified in the routing
request.
<P>
</LI>
<LI><CODE>internal</CODE><BR>
<P>The classical rule; search the destination in
RegistrationTable
<P>
</LI>
<LI><CODE>parent</CODE><BR>
<P>Route the call using information sent by the parent gatekeeper in
reply to an ARQ the gatekeeper will send.
You can define your parent gatekeeper using the 
<A HREF="#endpoint">Endpoint</A> section.
<P>
</LI>
<LI><CODE>neighbor</CODE><BR>
<P>Route the call using neighbors by exchanging LRQ messages.
<P>
</LI>
<LI><CODE>dns</CODE><BR>
<P>The destination is resolved from DNS A records.
<P>
</LI>
<LI><CODE>sql</CODE><BR>
<P>Route calls by rewriting the called alias with a database query or send them directly to a destination IP. The database parameters are specified in the 
<A HREF="#routingsql">Routing::Sql</A> section.
<P>
</LI>
<LI><CODE>vqueue</CODE><BR>
<P>Use the virtual queue mechanism and generate a RouteRequest
event to let an external application do the routing.
<P>
</LI>
<LI><CODE>numberanalysis</CODE><BR>
<P>Provides support for overlapped digit sending for ARQ messages.
This also partially supports Setup messages (no overlapped sending
- only number length validation).
<P>
</LI>
<LI><CODE>enum</CODE><BR>
<P>ENUM (RFC3761) is a method to use DNS lookups to convert
real International Direct Dialing E.164 numbers into H.323 dialing information. The default servers
are <CODE>e164.voxgratia.net</CODE>, <CODE>e164.org</CODE> and <CODE>e164.arpa</CODE>.
To specify your own server you may either specify the list via the ENUMserver variable in
the RoutedMode section or specify an environmental variable PWLIB_ENUM_PATH with the address of your preferred
enum servers.  Multiple servers should be separated by a colon(:) on Linux and a semicolon (;) on Windows. 
(PWLIB_ENUM_PATH is supported starting with PWLib 1.8.0)
<P>The enum policy replaces the destination with the information returned by the ENUM server, 
so you must have the appropriate routing policies to continue processing the call after the enum policy. 
You should have the srv and dns policies after the enum policy, because the new location is often 
returned in the form of 'number@gatekeeper' and the srv and dns policies are needed to resolve this.
<P>Finally, keep in mind that each routing check with the enum policy requires a DNS lookup. 
To speed up your routing, make sure you resolve internal destinations before the enum policy is applied.
<P>
</LI>
<LI><CODE>srv</CODE><BR>
<P>DNS SRV or H.323 Annex O allows for the routing of calls using a H.323 URI. 
Addresses can be configured as user (at) domain. H.323 URIs are stored in the 
SRV DNS records of the domain and are queried to find the destination. 
<P>
</LI>
<LI><CODE>rds</CODE><BR>
<P>URN RDS or Universal resources name resolver discovery system is a system (as defined in RFC 2915 Sect 7.2 
whereby domain names SRV records are hosted on other domains. In this policy the servers set by 
[RoutedMode] RDSServers are queried to resolve URI's whose domains do not have SRV records. This can be used
to virtually host URL domains or centralize the control of SRV records.
<P>
</LI>
<LI><CODE>catchall</CODE><BR>
<P>This policy will route all calls that reach it to one endpoint specified in the 
<A HREF="#routingcatchall">Routing::CatchAll</A> section.
You can use it as a fallback at the end of the policy chain to route all calls which would otherwise fail.
<P>
</LI>
</UL>
<P>
<P>Default configuration for routing policies is as follows:
<DL>
<P>
<BLOCKQUOTE>
<CODE>[RoutingPolicy]<BR>
default=explicit,internal,parent,neighbor</CODE>
</BLOCKQUOTE>
</DL>
<P>If one policy does not match, the next policy is tried.
<P>These policies can be applied to a number of routing request types and routing input data. The different types are
ARQ, LRQ, Setup and Facility (with the callForwarded reason).
There is also the general routing policy, which is a
default for the other types.
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE>
<CODE>[RoutingPolicy]<BR>
h323_ID=dns,internal<BR>
002=neighbor,internal<BR>
Default=internal,neighbor,parent</CODE>
</BLOCKQUOTE>
</DL>
<P>When a message is received which requires a routing
decision, all calls to an alias of the h323_ID type will be
resolved using DNS. If DNS fails to resolve the alias, it is
matched against the internal registration table. If a call is
requested to an alias starting with 002, first the neighbors
are checked and then the internal registration table. If the
requested alias is not an h323_ID or an alias starting with
002, the default policy is used by querying the internal
registration table, then the neighbors, and if that fails the
parent.
<P>For the ARQ, LRQ, Setup and Facility messages one would use the
[RoutingPolicy::OnARQ], [RoutingPolicy::OnLRQ],
[RoutingPolicy::OnSetup] and [RoutingPolicy::OnFacility] sections
using the syntax explained above.
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE>
<CODE>[RoutingPolicy::OnARQ]<BR>
default=numberanalysis,internal,neighbor</CODE>
</BLOCKQUOTE>
</DL>
<P>A typical ENUM routing setup would look like this:
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE>
<CODE>[RoutingPolicy]<BR>
default=explicit,internal,enum,srv,dns,internal,parent,neighbor</CODE>
</BLOCKQUOTE>
</DL>
<P>
<P>
<H2><A NAME="rewrite"></A> 6.2 Section [RasSrv::RewriteE164]</H2>

<P>This section defines the rewriting rules for dialedDigits (E.164 number).
<P>
<DL>
<DT><B>Format:</B><DD><P><CODE>[!]original-prefix=target-prefix</CODE>
<P>If the number begins with <CODE>original-prefix</CODE>,
it is rewritten to <CODE>target-prefix</CODE>.
If the `<CODE>!</CODE>' flag precedes the <CODE>original-prefix</CODE>, the sense is inverted
and the target-prefix is prepended to the dialed number. Special wildcard
characters (<CODE>'.'</CODE> and <CODE>'%'</CODE>) are available.
<DT><B>Example:</B><DD><P><CODE>08=18888</CODE>
<P>If you dial <CODE>08345718</CODE>, it is rewritten to <CODE>18888345718</CODE>.
<DT><B>Example:</B><DD><P><CODE>!08=18888</CODE>
<P>If you dial <CODE>09345718</CODE>, it is rewritten to <CODE>1888809345718</CODE>.
</DL>
<P>Option:
<UL>
<LI><CODE>Fastmatch=08</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Only rewrite dialDigits beginning with the specified prefix.
</LI>
</UL>
<P>
<H2><A NAME="rewrite"></A> 6.3 Section [RasSrv::RewriteAlias]</H2>

<P>This section defines the rewriting rules for aliases. This can be used to
map gatekeeper assigned aliases to registered endpoints.
<P>
<DL>
<DT><B>Format:</B><DD><P><CODE>[!]original-alias=target-alias</CODE>
<P>If the alias is <CODE>original-alias</CODE>,
it is rewritten to <CODE>target-alias</CODE>.
<DT><B>Example:</B><DD><P><CODE>bill=033123456</CODE>
</DL>
<P>
<P>
<H2><A NAME="gwrewrite"></A> 6.4 Section [RasSrv::GWRewriteE164]</H2>

<P>This section describes rewriting the dialedDigits E.164 number depending on
the gateway a call has come from or is being sent to. This allows for more
flexible manipulation of the dialedDigits for routing etc. In combination
with the 
<A HREF="#rewrite">RasSrv::RewriteE164</A> you can have triple
stage rewriting:
<P>
<BLOCKQUOTE><CODE>
<PRE>
Call from "gw1", dialedDigits 0867822
                |
                |
                V
Input rules for "gw1", dialedDigits now 550867822
                |
                |
                V
Global rules, dialedDigits now 440867822
                |
                |
                V
Gateway selection, dialedDigits now 440867822, outbound gateway "gw2"
                |
                |
                V
Output rules for "gw2", dialedDigits now 0867822
                |
                |
                V
Call to "gw2", dialedDigits 0867822
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DL>
<DT><B>Format:</B><DD><P><CODE>gw-alias=in|out=[!]original-prefix=target-prefix[;in|out...]</CODE>
<P>If the call matches the gateway, the direction and begins with
<CODE>original-prefix</CODE> it is rewritten to <CODE>target-prefix</CODE>.
If the `<CODE>!</CODE>' flag precedes the <CODE>original-prefix</CODE>, the sense is inverted.
Special wildcard characters (<CODE>'.'</CODE> and <CODE>'%'</CODE>) are available.
Multiple rules for the same gateway should be separated by ';'.
<DT><B>Example:</B><DD><P><CODE>gw1=in=123=321</CODE>
<P>If a call is received from "gw1" to <CODE>12377897</CODE>, it is rewritten to <CODE>32177897</CODE>
before further action is taken.
</DL>
<P>
<P>
<H2>6.5 Section [Endpoint::RewriteE164]</H2>

<P>Once you specify prefix(es) for your gatekeeper endpoint, the parent
gatekeeper will route calls with <B>dialedDigits</B> beginning with that prefixes.
The child gatekeeper can rewrite the destination according to the rules
specified in this section. By contrast, when an internal endpoint calls
an endpoint registered to the parent gatekeeper, the source will be
rewritten reversely.
<P>
<DL>
<DT><B>Format:</B><DD><P><CODE>external prefix=internal prefix</CODE>
</DL>
<P>For example, if you have the following configuration,
<P>
<BLOCKQUOTE><CODE>
<PRE>
                        [Parent GK]
                        ID=MasterGK
                        /         \
                       /           \
                      /             \
                     /               \
                [Child GK]          [EP3]
                ID=ProxyGK          E164=18888200
                Prefix=188886
                /       \
               /         \
              /           \
           [EP1]         [EP2]
           E164=601      E164=602
</PRE>
</CODE></BLOCKQUOTE>
<P>With this rule:
<BLOCKQUOTE><CODE>
<PRE>
188886=6
</PRE>
</CODE></BLOCKQUOTE>
<P>When EP1 calls EP3 by <CODE>18888200</CODE>, the CallingPartyNumber in the Q.931 Setup
will be rewritten to <CODE>18888601</CODE>. Conversely, EP3 can reach EP1 and EP2
by calling <CODE>18888601</CODE> and <CODE>18888602</CODE>, respectively. In consequence, an
endpoint registered to the child gatekeeper with prefix '<CODE>6</CODE>' will appear
as an endpoint with prefix '<CODE>188886</CODE>', for endpoints registered to
the parent gatekeeper.
<P>The section does not relate to the section
<A HREF="#rewrite">RasSrv::RewriteE164</A>,
though the latter will take effect first.
<P>
<H2><A NAME="routingsql"></A> 6.6 Section [Routing::Sql]</H2>

<P>Rewrite the called alias with a SQL query.
Supports routing OnARQ, OnLRQ and OnSetup.
<P>If the string returned from the database is 'REJECT' (upper or lower case),
the call is rejected. If the string matches a dotted IP address, it is
taken as destination IP otherwise it is treated as a new destination alias.
If 2 columns are returned, the first is treated as the new destination alias
and the second is treated as new destination IP.
<P>If multiple rows of destination IPs are returned they are used as alternative routes
for failover and GnuGk will try them in order.
<P>When at least one destination IP is specified or the call is rejected,
the SQL policy will end the routing chain.
If only the alias is changed, the chain continues with this updated alias.
<P>When rejecting a call, the 2nd column can contain an integer designating the
reject reason (H.225 AdmissionRejectReason for registered calls,
H.225 LocationRejectReason for neighbor calls,
H.225 disconnect reason for unregistered calls).
<P>If the database returns nothing, the call is passed on unchanged.
<P>
<UL>
<LI><CODE>Driver=MySQL | PostgreSQL | Firebird | ODBC | SQLite</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>SQL database driver to use. Currently, <CODE>MySQL</CODE>, <CODE>PostgreSQL</CODE>, <CODE>Firebird</CODE>, <CODE>ODBC</CODE> and <CODE>SQLite</CODE> drivers
are implemented. GnuGk supports only version 3 of SQLite.
<P>
</LI>
<LI><CODE>Host=DNS[:PORT] | IP[:PORT]</CODE><BR>
Default: <CODE>localhost</CODE><BR>
<P>SQL server host address. Can be in the form of <CODE>DNS[:PORT]</CODE> or <CODE>IP[:PORT]</CODE>.
Like <CODE>sql.mycompany.com</CODE> or <CODE>sql.mycompany.com:3306</CODE> or <CODE>192.168.3.100</CODE>.
<P>
</LI>
<LI><CODE>Database=gnugk</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>The database name to connect to.
<P>
</LI>
<LI><CODE>Username=gnugk</CODE><BR>
<P>The username used to connect to the database.
<P>
</LI>
<LI><CODE>Password=secret</CODE><BR>
<P>The password used to connect to the database.
If the password is not specified, a database connection attempt 
without any password will be made.
<P>
</LI>
<LI><CODE>Query=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query to fetch the new destination number.
The query is parameterized - that means parameter
replacement is made before each query is executed. The following parameters are defined:
<UL>
<LI><CODE>%c</CODE> - the called alias</LI>
<LI><CODE>%p</CODE> - the called IP (only available on Setup, empty otherwise)</LI>
<LI><CODE>%s</CODE> - the calling IP</LI>
<LI><CODE>%r</CODE> - the calling aliases</LI>
<LI><CODE>%{Calling-Station-Id}</CODE> - the calling station ID (same value as used in accounting and authentication events)</LI>
<LI><CODE>%i</CODE> - the call ID</LI>
<LI><CODE>%m</CODE> - the message type (ARQ, LRQ or Setup)</LI>
<LI><CODE>%{client-auth-id}</CODE> - an ID provided to GnuGk when authenticating the call (through SqlAuth)</LI>
</UL>

Some of these can be empty if they aren't included in the ARQ, LRQ or Setup message.
<P>If the query returns no rows, the current alias is used.
Otherwise, the first result row is used.
<P>Query string examples.  Note that these are examples; the actual structure and schema
are user defined, as are the various field names in these examples.  GnuGk is simply expecting either IP addresses or aliases as a result of the query.
<P>
<BLOCKQUOTE><CODE>
<PRE>
SELECT destination FROM routes WHERE called = '%c'
SELECT concat(prefix,'%c') FROM routes WHERE prefix = LEFT('%c', 5)
SELECT gatewayip FROM routes WHERE prefix = LEFT('%c',5)
SELECT concat(prefix,'%c'), gatewayip FROM routes WHERE route = LEFT('%c', 5) limit 3
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
</UL>
<P>
<H2><A NAME="numberanalysis"></A> 6.7 Section [Routing::NumberAnalysis]</H2>

<P>This section defines rules for the <CODE>numberanalysis</CODE> routing policy.
The policy checks a dialed number for minimum and/or maximum number of digits
and sends ARJ, if necessary (number of digits is out of range), to support
overlapped digit sending. It also partially supports Setup messages (no overlapped sending
- only number length validation).
<P>
<DL>
<DT><B>Format:</B><DD><P><CODE>prefix=MIN_DIGITS[:MAX_DIGITS]</CODE>
<P>If the number matches the <CODE>prefix</CODE>, it is verified to consist of at least
<CODE>MIN_DIGITS</CODE> digits and (if MAX_DIGITS is present) at most <CODE>MAX_DIGITS</CODE>
digits. Special wildcard characters (<CODE>!</CODE>, <CODE>'.'</CODE> and <CODE>'%'</CODE>) are available.
If the number is too short, an ARJ is send with <CODE>rejectReason</CODE> set to <CODE>incompleteAddress</CODE>.
If the number is too long, an ARJ is send with <CODE>rejectReason</CODE> set to <CODE>undefinedReason</CODE>.
Prefix list is searched from the longest to the shortest prefix for a match.
For Setup messages, a Release Complete with "badFormatAddress" is sent when the number
has an incorrect length.
<P>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RoutingPolicy::OnARQ]
default=numberanalysis,internal

[Routing::NumberAnalysis]
0048=12
48=10
.=6:20
</PRE>
</CODE></BLOCKQUOTE>
<P>Calls to destinations starting with 0048 require at least 12 digits,
to 48 we require 10 digits and to all other destinations at least 6 and at most 20 digits.
</DL>
<P>
<H2><A NAME="routingcatchall"></A> 6.8 Section [Routing::CatchAll]</H2>

<P>
<UL>
<LI><CODE>CatchAllIP=1.2.3.4</CODE><BR>
Default: <CODE>(empty)</CODE><BR>
<P>Specify an IP address to route all calls to. This overrides CatchAllAlias.
<P>
</LI>
<LI><CODE>CatchAllAlias=Frank</CODE><BR>
Default: <CODE>catchall</CODE><BR>
<P>If CatchAllIP is not specified, then route all calls to this alias.
</LI>
</UL>
<P>
<P>
<H2><A NAME="clirewrite"></A> 6.9 Section [RewriteCLI]</H2>

<P>This section contains a set of rewrite rules for ANI/CLI/H.323_ID numbers (Caller ID).
The rewrite process is done in two stages - inbound rewrite and outbound rewrite.
The inbound rewrite is done before any other Q.931 Setup message processing
(such as inbound GWRewrite, authentication, accounting, ...), and because it alters the Calling-Station-Id it will have
an effect in the authorization and accounting modules.
The outbound rewrite takes place just before the Setup message is to be forwarded
and its effect is visible only to the callee.
<P>An inbound rewrite rule can be matched by a caller's IP and a dialed number
or an original CLI/ANI.
An outbound rewrite rule can be matched by a caller's IP, callee's IP and
a dialed number or a destination number (the dialed number after rewrite)
or a CLI/ANI (after inbound rewrite).
<P>This module also provides CLIR (Calling Line Identification Restriction)
feature that can be configured for each endpoint (rule).
<P>
<UL>
<LI><CODE>ProcessSourceAddress=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>In addition to rewriting a Calling-Party-Number Information Element ("IE"), the sourceAddress
element of a H.225.0 Setup message can be rewritten, so both contain
consistent information.
<P>
</LI>
<LI><CODE>RemoveH323Id=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>When a sourceInfo element of an H.225.0 Setup message is rewritten,
aliases of type H323_ID, email_ID and url_ID can be left untouched
if this option is disabled.
<P>
</LI>
<LI><CODE>CLIRPolicy=apply</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>A global Presentation Indicator ("PI") processing policy can be set up.
This policy will be applied to all CLI rewrite rules that do not override it.
Possible choices are <CODE>forward</CODE> - just forward the received PI as-is,
<CODE>apply</CODE> - examine the received PI and hide CLI if it is set to "presentation
restricted" and <CODE>applyforterminals</CODE> - similar to <CODE>apply</CODE> except that the number
is removed only when the call is sent to a terminal, not a gateway.
<P>
</LI>
</UL>
<P>
<DL>
<DT><B>Format for an inbound rule:</B><DD><P><CODE>in:CALLER_IP=[pi=[allow|restrict][,forward|apply|applyforterminals]] [cli:|dno:]number_prefix(=|*=|~=|^=|/=)NEW_CLI[,NEW_CLI]...</CODE>
<P>The <CODE>in:</CODE> prefix tells that this is an inbound rule and the <CODE>CALLER_IP</CODE>
will be used to match the rule (it can be a single IP or an entire subnet).<BR>
<P>The optional <CODE>pi=</CODE> parameter controls CLIR (Calling Line Identification Restriction)
features. Specifying either <CODE>allow</CODE> or <CODE>restrict</CODE> forces presentation indicator
to be set to "presentation allowed" or "presentation restricted". <CODE>forward</CODE>, <CODE>apply</CODE>
and <CODE>applyforterminals</CODE> controls how the received (if any) presentation indicator
is processed by the gatekeeper. <CODE>forward</CODE> means forward it to the callee as-is,
<CODE>apply</CODE> means hiding CLI if the PI is set to "presentation restricted", <CODE>applyforterminals</CODE>
is similar to <CODE>apply</CODE>, except that CLI is hidden only when sending the call to a terminal,
not a gateway.<BR>
<P>The prefix <CODE>cli:</CODE> or <CODE>dno:</CODE> (the default) selects what number will be used
to match the <CODE>number_prefix</CODE> - a caller id (CLI/ANI) or a dialed number.
Number matching/rewriting can be done in five ways:
<UL>
<LI><CODE>=</CODE> - a <CODE>cli</CODE> or <CODE>dno</CODE> number will be matched using a prefix
match against <CODE>number_prefix</CODE> and, if the match is found,
CLI will be replaced with NEW_CLI.</LI>
<LI><CODE>~=</CODE> - a <CODE>cli</CODE> or <CODE>dno</CODE> number will be matched using an identity
match against <CODE>number_prefix</CODE> and, if both numbers are the same,
CLI will be replaced with NEW_CLI.</LI>
<LI><CODE>*=</CODE> - (VALID ONLY FOR <CODE>cli</CODE>) a <CODE>cli</CODE> number will be matched using
a prefix match against <CODE>number_prefix</CODE> and, if the match is found,
the matched CLI prefix (<CODE>number_prefix</CODE>) will be replaced
with a NEW_CLI prefix.</LI>
<LI><CODE>^=</CODE> - a <CODE>cli</CODE> or <CODE>dno</CODE> number will be matched using a prefix
match against <CODE>number_prefix</CODE> and, if the match is found,
H.323_ID will be replaced with NEW_CLI, Calling-Station-Id will remain unchanged.</LI>
<LI><CODE>/=</CODE> - a <CODE>cli</CODE> or <CODE>dno</CODE> number will be matched using an identity
match against <CODE>number_prefix</CODE> and, if both numbers are the same,
H.323_ID will be replaced with NEW_CLI, Calling-Station=Id will remain unchanged,</LI>
</UL>

After the equality (=/&nbsp;=/*=/^=//=) sign, there follows a list of new CLI values to be used.
If more than one value is specified, one will be chosen on a random basis.
It's possible to specify whole number ranges, like 49173600000-49173699999
(for number ranges CLIs should have a fixed length).
There is a special string constant "any", that can be used in place
of the <CODE>CALLER_IP</CODE> or the <CODE>number_prefix</CODE>. To enable <CODE>CLIR</CODE> for this rule,
use a special string constant <CODE>"hide"</CODE> instead of the list of new CLI values.
Note that CLIR is far more useful for outbound rules.
<P>
<DT><B>Example 1:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
in:192.168.1.1=dno:5551=3003
in:192.168.1.1=cli:1001=2222
in:192.168.1.1=any=1111
</PRE>
</CODE></BLOCKQUOTE>
<P>These rules state that for calls from the IP 192.168.1.1:
1) if the user dialed a number beginning with 5551, set CLI to 3003,
2) if the call is from user with CLI beginning with 1001, set CLI to 2222,
3) for other calls from this IP, set CLI to 1111.
<P>
<DT><B>Example 2:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
in:192.168.1.0/24=any=18001111
in:192.168.2.0/24=any=18002222
in:any=any=0
</PRE>
</CODE></BLOCKQUOTE>
<P>These rules state that:
1) for calls from the network 192.168.1.0/24, set CLI to 18001111,
2) for calls from the network 192.168.2.0/24, set CLI to 18002222,
3) for other calls, set CLI to 0.
<P>
<DT><B>Example 3:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
in:192.168.1.0/24=0048*=48
in:192.168.1.0/24=0*=48
in:any=100.~=48900900900
</PRE>
</CODE></BLOCKQUOTE>
<P>These rules state that:
1) for calls from the network 192.168.1.0/24, rewrite 0048 to 48 (example - 0048900900900 => 48900900900),
2) for other calls from the network 192.168.1.0/24, rewrite 0 to 48 (example - 0900900900 => 48900900900),
3) for other calls, if CLI is 4 digits and starts with 100, set it to 48900900900.
<P>
<DT><B>Example 4 (CLIR):</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
in:192.168.1.0/24=any=hide
</PRE>
</CODE></BLOCKQUOTE>
<P>This example causes caller's number to be removed from Setup messages
originating from the 192.168.1.0/24 network. It also causes proper presentation
and screening indicators to be set in Setup messages.
</DL>
<P>
<DL>
<DT><B>Format for an outbound rule:</B><DD><P><CODE>out:CALLER_IP=CALLEE_IP [pi=[allow|restrict][,forward|apply|applyforterminals]] [cli:|dno:|cno:]number_prefix(=|~=|*=)NEW_CLI[,NEW_CLI]...</CODE>
<P>The <CODE>out:</CODE> prefix tells that this is an outbound rule, the <CODE>CALLER_IP</CODE>
and the <CODE>CALLEE_IP</CODE> will be used to match the rule and can be a single IP
or a subnet address.<BR>
<P>The optional <CODE>pi=</CODE> parameter controls CLIR (Calling Line Identification Restriction)
features. Specifying either <CODE>allow</CODE> or <CODE>restrict</CODE> forces the presentation indicator
to be set to "presentation allowed" or "presentation restricted". <CODE>forward</CODE>, <CODE>apply</CODE>
and <CODE>applyforterminals</CODE> controls how the received (if any) presentation indicator
is processed by the gatekeeper. <CODE>forward</CODE> means just to forward it to the callee as-is,
<CODE>apply</CODE> means hiding CLI if the PI is set to "presentation restricted", <CODE>applyforterminals</CODE>
is similar to <CODE>apply</CODE>, except that the CLI is hidden only when sending the call to a terminal,
not a gateway.<BR>
<P>The prefix <CODE>cli:</CODE>, <CODE>dno:</CODE> (the default) or <CODE>cno:</CODE> selects what number
will be used to match the <CODE>number_prefix</CODE> - a caller id (CLI/ANI),
a dialed number or a destination/called number (the dialed number after rewrite).
Number matching/rewriting can be done in three ways:
<UL>
<LI><CODE>=</CODE> - a <CODE>cli</CODE> or <CODE>dno</CODE> number will be matched using a prefix
match against <CODE>number_prefix</CODE> and, if the match is found,
CLI will be replaced with NEW_CLI,</LI>
<LI><CODE>~=</CODE> - a <CODE>cli</CODE> or <CODE>dno</CODE> number will be matched using an identity
match against <CODE>number_prefix</CODE> and, if both numbers are the same,
CLI will be replaced with NEW_CLI,</LI>
<LI><CODE>*=</CODE> - (VALID ONLY FOR <CODE>cli</CODE>) a <CODE>cli</CODE> number will be matched using
a prefix match against <CODE>number_prefix</CODE> and, if the match is found,
the matched CLI prefix (<CODE>number_prefix</CODE>) will be replaced
with a NEW_CLI prefix.</LI>
</UL>

After the equality sign (=/&nbsp;=/*=), a list of new CLI values to be used is specified.
If more than one value is configured, one will be chosen on a random basis.
It's possible to specify entire number ranges, like 49173600000-49173699999.
There is a special string constant "any" which can be used in place
of the <CODE>CALLER_IP</CODE>, the <CODE>CALLEE_IP</CODE> or the <CODE>number_prefix</CODE>. 
To enable <CODE>CLIR</CODE> for this rule, use a special string constant <CODE>"hide"</CODE>
or <CODE>"hidefromterminals"</CODE> instead of the list of new CLI values.
<P>
<DT><B>Example 1:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
out:any=192.168.1.1 any=1001
out:any=192.168.1.2 any=1002
</PRE>
</CODE></BLOCKQUOTE>
<P>These rules set a fixed ANI/CLI for each terminating IP:
1) present myself with ANI 1001, when sending calls to IP 192.168.1.1,
2) present myself with ANI 1002, when sending calls to IP 192.168.1.2.
<P>
<DT><B>Example 2:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
out:any=192.168.1.1 any=1001-1999,3001-3999
</PRE>
</CODE></BLOCKQUOTE>
<P>This rule randomly selects ANI/CLI from range 1001-1999, 3001-3999
for calls sent to 192.168.1.1.
<P>
<DT><B>Example 3 (CLIR):</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
out:any=any any=hidefromterminals
out:192.168.1.1=any any=hide
</PRE>
</CODE></BLOCKQUOTE>
<P>In this example each subscriber has enabled CLIR, so all calls to terminals
will have a caller's number removed and presentation/screening indicators set.
Calls to gateways will have the presentation indicator set to "presentation restricted"
and the caller's number will not be removed to allow proper call routing and number
removal at the destination equipment.<BR>
One exception to these rules are calls from 192.168.1.1 which will have a caller's number
always removed, no matter whether calling a terminal or a gateway.
<P>
<DT><B>Example 4 (CLIP):</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
out:any=192.168.1.1 any=hide
</PRE>
</CODE></BLOCKQUOTE>
<P>In this example CLIP (Calling Line Identification Presentation) feature
is disabled for the user 192.168.1.1.
<P>
<DT><B>Example 5 (CLIR):</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
out:192.168.1.1=any pi=restrict,apply cli:.*=.
out:any=any pi=allow cli:.*=.
</PRE>
</CODE></BLOCKQUOTE>
<P>These rules do not change CLI (.*=.) and:
1) enable CLIR for an endpoint 192.168.1.1. <CODE>apply</CODE> tells the gatekeeper
to not only set the PI, but also to hide the number.
2) force CLI presentation for other endpoints.
</DL>
<P>
<P>The rule matching process has a strictly defined order:
<OL>
<LI>the closest caller's IP match is determined (closest means with the longest
network mask - single IPs have the highest priority, "any" has the lowest
priority),</LI>
<LI>(outbound rules) the closest callee's IP match is determined,</LI>
<LI>the longest matching prefix/number is searched for the given IP/IP pair
in the following order:
<OL>
<LI><CODE>dno:</CODE> type (dialed number) rules are searched,</LI>
<LI><CODE>cno:</CODE> type (destination/called number) rules are searched,</LI>
<LI><CODE>cli:</CODE> type (caller id) rules are searched.</LI>
</OL>
</LI>
</OL>

After a match for caller's/caller's IP is found, no more rules
are checked, even if no prefix/number is matched inside the set of rules
for these IPs.
<P>
<P>On the Windows platform, there is a problem with duplicated config
keys in INI files, so GnuGk provides a workaround for this restriction. This example
will not work because of the same key (<CODE>in:192.168.1.1</CODE>):
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
in:192.168.1.1=1001=2001
in:192.168.1.1=any=2000
</PRE>
</CODE></BLOCKQUOTE>

As a workaround, you can use a string with percent signs (%) at the beginning
and at the end before the key. This prefix will be automatically stripped
from the key name before loading rules:
<BLOCKQUOTE><CODE>
<PRE>
[RewriteCLI]
%r1% in:192.168.1.1=1001=2001
%r2% in:192.168.1.1=any=2000
</PRE>
</CODE></BLOCKQUOTE>

<H2><A NAME="s7">7. RAS Configuration</A></H2>

<P>
<H2><A NAME="gwprefixes"></A> 7.1 Section [RasSrv::GWPrefixes]</H2>

<P>This section configures how dialed E.164 numbers are routed to a specific gateway.
<P>
<DL>
<DT><B>Format:</B><DD><P><CODE>gw-alias=prefix[:=priority][,prefix[:=priority],...]</CODE>
<P>Note that you must specify the alias of the gateway.
If a gateway has registered with the specified alias, all numbers beginning with
the prefixes are routed to that gateway. Special characters <CODE>.</CODE> and <CODE>!</CODE>
can be used here to match any digit or to disable the prefix.
A priority can be given to each prefix for each gateway (using := syntax),
so that if several gateways match the dialed number, the one
with the highest prefix priority will be selected to route the call (when
the ActivateFailover switch is ON, the call will be routed to all selected
gateways in order of the prefix priority).  A smaller value corresponds to
a higher priority.  Default value is 1.  If the prefix priority
and overlaps the GatewayPriority (see section 
<A HREF="#epconfig">[EP::...]</A>), the prefix priority will be preferred.
<P>In the following example, the gateway "test-gw" will be responsible for
prefixes "02" and "03" with a priority of 3, and for "04" with a priority
of 1.
<P>
<DT><B>Example:</B><DD><P><CODE>test-gw=02,03:=3,04:=1</CODE>
</DL>
<P>
<H2>7.2 Section [RasSrv::PermanentEndpoints]</H2>

<P>In this section you may configure endpoints that don't have RAS support
or that you don't want to be expired. Their records will always
remain in the registration table of the gatekeeper.
However, you can still unregister it via the status port.
Special characters <CODE>.</CODE> and <CODE>!</CODE>
can be used with prefixes here to match any digit and disable the prefix.
You may use := syntax to set a prefix priority in the same manner as in 
<A HREF="#gwprefixes">[RasSrv::GWPrefixes]</A> section.
<DL>
<DT><B>Format:</B><DD><P><CODE>IP[:port]=alias[,alias,...;prefix[:=priority][,prefix[:=priority]]...]</CODE>
<DT><B>Example:</B><DD><P>For gateway,
<BLOCKQUOTE>
<CODE>10.0.1.5=MyGW;009,008:=2,0.7:=3</CODE>
</BLOCKQUOTE>

For terminal,
<BLOCKQUOTE>
<CODE>10.0.1.10:1720=700</CODE>
</BLOCKQUOTE>
</DL>
<P>
<P>
<H2>7.3 Section [RasSrv::RRQFeatures]</H2>

<P>
<UL>
<LI><CODE>AcceptEndpointIdentifier=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Whether to accept <B>endpointIdentifier</B> specified in a full RRQ.
<P>
</LI>
<LI><CODE>AcceptGatewayPrefixes=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>A gateway can register its prefixes with the gatekeeper by sending
<B>supportedPrefixes</B> in the <B>terminalType</B> field of the RRQ.
This option defines whether to accept the specified prefixes of a gateway.
<P>
</LI>
<LI><CODE>AcceptMCUPrefixes=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>A MCU can register its prefixes with the gatekeeper by sending 
<B>supportedPrefixes</B> in the <B>terminalType</B> field of the RRQ.
This option defines whether to accept the specified prefixes of a MCU.
<P>
<P>
</LI>
<LI><CODE>OverwriteEPOnSameAddress=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>In some networks an endpoint's IP address may change unexpectedly.  This
may happen when an endpoint is using a PPP connection (e.g. modem or ADSL).
This option defines how to handle a registration request (RRQ) from an IP
address which does not match what we have stored.  The default action is
to reject the request.  With this option enabled the conflicting request
will cause an unregister request (URQ) to be sent for the existing IP
address and the entry to be removed, allowing the endpoint to register
with the new address.
<P>
</LI>
<LI><CODE>IRQPollCount=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>When the gatekeeper does not receive a keep-alive RRQ from an endpoint
within the TimeToLive time period, it sends an IRQ message to "poll" the endpoint
and check if it is alive. After IRQPollCount messages are sent and no reply
is received, the endpoint is unregistered. To disable this feature (and unregister
endpoints immediately after TimeToLive timeout), set this variable to 0.
IRQ poll interval is 60 seconds.
<P>
</LI>
<LI><CODE>SupportDynamicIP=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>When the IP address of an endpoint changes, the gatekeeper can maintain registration. 
This will force the EP to fully re-register if its IP address changes. 
<P>
</LI>
<LI><CODE>AccHTTPLink=https://billing.mysite.com?account=%a&amp;password=%p</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>You can assign a URL for clients to access to view billing information.
If using PacPhone you can also add wildcards for the client to use so the clients 
H323ID and password can be used to directly access their account information.
%a - H323ID   %p - password 
<P>
</LI>
<LI><CODE>AliasTypeFilter=terminal;h323id,dialeddigits</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Use this setting where endpoints send multiple H225_AliasAddress and some Aliases are
shared across multiple registrations. You can filter out the shared alias types for
any given endpoint type. The registrations will keep all alias types listed in the
filter setting and remove all others.
You must have separate AliasTypeFilter entries for each endpoint type.
Valid endpoint types are: gatekeeper, gateway, mcu and terminal.
Valid filters are: h323id, dialeddigits, url, transport, email and partynumber.
NOTE: If no alias is found that match the filter then all aliases are registered.
</LI>
</UL>
<P>
<P>
<H2>7.4 Section [RasSrv::ARQFeatures]</H2>

<P>
<UL>
<LI><CODE>ArjReasonRouteCallToGatekeeper=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>If enabled, the gatekeeper rejects an answered ARQ without a pre-existing
CallRec found in the CallTable by reason <B>routeCallToGatekeeper</B>
in routed mode.
The endpoint shall release the call immediately and re-send call Setup
to the gatekeeper.
<P>
</LI>
<LI><CODE>RemoveTrailingChar=#</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Specify the trailing character to be removed in <B>destinationInfo</B>.
For example, if your endpoint incorrectly contains a termination character
such as `#' in <B>destinationInfo</B> you may remove it with this option.
<P>
</LI>
<LI><CODE>RoundRobinGateways=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Enable/disable round-robin gateway selection if more than one gateway
matches a dialed number. If disabled, the first available gateway will be selected.
Otherwise, subsequent calls will be sent to gateways in round-robin fashion.
<P>
</LI>
</UL>
<P>
<H2>7.5 Section [RasSrv::AssignedAlias]</H2>

<P>This allows the assigning of aliases to endpoints as they register, allowing them to 
set their fully qualified E.164 or URI addresses.
<P>
<DL>
<DT><B>Example:</B><DD><P>
<PRE>
[RasSrv::AssignedAlias]
1234=3323465777,me@mysite.com 
</PRE>
</DL>
<P>
<H2>7.6 Section [AssignedAliases::SQL]</H2>

<P>This section configures GnuGk to read the assigned aliases from a database.
You can use the same database parameters as defined in 
<A HREF="#sqlpasswordauth">[SQLPasswordAuth]</A>.
<P>
<UL>
<LI><CODE>Query=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines the SQL query used to retrieve the assigned aliases from the database.
<P>One parameter is defined:
<UL>
<LI><CODE>%u</CODE> - endpoint alias</LI>
</UL>
<P>Sample query string:
<BLOCKQUOTE><CODE>
<PRE>
SELECT assignedalias FROM users WHERE alias = '%u' AND active
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
</UL>
<P>
<H2>7.7 Section [RasSrv::AssignedGatekeeper]</H2>

<P>This allows the assigning of a gatekeeper based upon the H323ID or the
apparent source IP address of the registering endpoint.
The received H323ID in the GRQ is checked to see if it has a prefix
for an assigned gatekeeper or the IP is in a range of an assigned
gatekeeper.
The endpoint is then advised in the GCF to register with that gatekeeper.
You may have multiple gatekeepers for a specific prefix.  The first
is assigned as the primary and others are then the alternates.
(requires H.323v6)
<P>
<DL>
<DT><B>Examples:</B><DD><P>
<PRE>
[RasSrv::AssignedGKs]
;; For Endpoint with H323ID starting with 01234
01234=x.x.x.x:1719
;; For Endpoints in the range of 195.71.129.0/24 or 195.71.131.0/24
^195\.71\.(129|131)\.[0-9]+$=x.x.x.x:1719
</PRE>
</DL>
<P>
<P>
<H2>7.8 Section [AssignedGatekeepers::SQL]</H2>

<P>This section allows 
<A HREF="http://www.gnugk.org/">GnuGk</A> to read the assigned gatekeepers from a database.
You can use the same database parameters as defined in 
<A HREF="#sqlpasswordauth">[SQLPasswordAuth]</A>.
<P>
<UL>
<LI><CODE>Query=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines the SQL query used to retrieve the assigned gatekeepers from the database.
<P>Two parameters are defined:
<UL>
<LI><CODE>%u</CODE> - endpoint alias</LI>
<LI><CODE>%i</CODE> - endpoint IP</LI>
</UL>
<P>Sample query string:
<BLOCKQUOTE><CODE>
<PRE>
SELECT assignedgatekeeper FROM users WHERE alias = '%u' AND active
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
</UL>
<P>
<P>
<H2>7.9 Section [NATedEndpoints]</H2>

<P>The gatekeeper can automatically detect whether an endpoint is behind NAT.
However, if the detection fails, you can specify it manually in this section.
<P>
<DL>
<DT><B>Format:</B><DD><P><CODE>alias=true | yes | 1</CODE>
<DT><B>Example:</B><DD><P>Specify that the endpoint with alias 601 is behind NAT.
<BLOCKQUOTE>
<CODE>601=true</CODE>
</BLOCKQUOTE>
</DL>
<P>
<H2><A NAME="s8">8. Authentication Configuration</A></H2>

<P>The following sections in the config file can be used to configure authentication.
<P>
<H2><A NAME="gkauth"></A> 8.1 Section [Gatekeeper::Auth]</H2>

<P>The section defines the authentication mechanism for the 
<A HREF="http://www.gnugk.org/">GNU Gatekeeper</A>.
<P>
<DL>
<DT><B>Syntax:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
authrule=actions

 &lt;authrule> := SimplePasswordAuth | AliasAuth | FileIPAuth | PrefixAuth | RadAuth | RadAliasAuth | SQLAuth | SQLAliasAuth | SQLPasswordAuth | CapacityControl | ...
 &lt;actions>  := &lt;control>[;&lt;ras>|&lt;q931>,&lt;ras>|&lt;q931>,...]
 &lt;control>  := optional | required | sufficient | alternative
 &lt;ras>      := GRQ | RRQ | URQ | ARQ | BRQ | DRQ | LRQ | IRQ
 &lt;q931>     := Setup | SetupUnreg
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>A rule may results in one of these three codes: ok, fail, next.
<UL>
<LI><CODE>ok</CODE> - The request is authenticated by this module.</LI>
<LI><CODE>fail</CODE> - The authentication fails and should be rejected.</LI>
<LI><CODE>next</CODE> - The rule cannot determine the request.</LI>
</UL>

There are also three ways to control a rule:
<UL>
<LI><CODE>optional</CODE> - If the rule cannot determine the request or accepts it, it is passed to next rule. Otherwise processing stops and the request is rejected.</LI>
<LI><CODE>required</CODE> - The requests should be authenticated by this module, or it would be rejected. The authenticated request would then be passed to next rule.</LI>
<LI><CODE>sufficient</CODE> - If the request is authenticated, it is accepted, or it would be rejected. That is, the rule determines the fate of the request. No rule should be put after a sufficient rule, since it won't take effect.</LI>
<LI><CODE>alternative</CODE> - similar to the <CODE>sufficient</CODE> rule, except that if the module cannot determine request fate, the request is passed to a next module.</LI>
</UL>
<P>Currently supported modules: (most only support a subset of the ras or q931 actions)
<UL>
<LI><CODE>SimplePasswordAuth/SQLPasswordAuth/H350PasswordAuth</CODE>
<P>These modules check the <B>tokens</B> or <B>cryptoTokens</B> fields of RAS message.
The tokens should contain at least generalID and password.
For <B>cryptoTokens</B>, <B>cryptoEPPwdHash</B> tokens hashed by simple MD5 and
<B>nestedcryptoToken</B> tokens hashed by HMAC-SHA1-96 (libssl must be installed!)
are now supported. For <B>tokens</B> tokens hashed by CAT (Cisco Access Token)
and a clear text username/password are now supported.
The ID and password are read from 
<A HREF="#password">[SimplePasswordAuth]</A> section,
or a SQL database for <CODE>SimplePasswordAuth</CODE> and <CODE>SQLPasswordAuth</CODE>
modules. The <CODE>MySQLPasswordAuth</CODE>
module is supported for backward compatibility. For H.350.2 authentication (<CODE>H350PasswordAuth</CODE>)
the <CODE>GkH350::Settings</CODE> section connection information must be completed.
<P>
</LI>
<LI><CODE>AliasAuth/SQLAliasAuth</CODE>
<P>The module can only be used to authenticate RegistrationRequest (RRQ).
The IP of an endpoint with a given alias should match a specified pattern.
For <CODE>AliasAuth</CODE> the pattern is defined in
<A HREF="#rrqauth">[RasSrv::RRQAuth]</A> the section.
For <CODE>SQLAliasAuth</CODE>, the pattern is retrieved from a SQL database as 
defined in the 
<A HREF="#sqlaliasauth">[SQLAliasAuth]</A> section.
<P>
</LI>
<LI><CODE>FileIPAuth</CODE>
<P>This module provides a simple way to restrict access to the gatekeeper
based on caller's IP or network.
<P>
</LI>
<LI><CODE>PrefixAuth</CODE>
<P>The IP or aliases of a request with a given prefix must match a specified
pattern. See section 
<A HREF="#prefixauth">[PrefixAuth]</A> for details.
Currently the module can only authorize
AdmissionRequest (ARQ) and LocationRequest (LRQ).
<P>
</LI>
<LI><CODE>RadAuth</CODE>
<P>Provides authentication based on H.235 username/password
security scheme. Authenticates RRQ, ARQ and Q.931 Setup through remote
RADIUS servers. It passes to RADIUS servers the usernames and passwords
extracted from CAT (Cisco Access Tokens) <B>tokens</B> carried
inside RRQ, ARQ or Setup packets. Therefore if your endpoints do not
support CATs or you do not need an authentication scheme based on
individually assigned usernames/password then this module would not be appropriate
(but you may check the <CODE>RadAliasAuth</CODE> module).
See section 
<A HREF="#radauth">[RadAuth]</A> for details.
<P>
</LI>
<LI><CODE>RadAliasAuth</CODE>
<P>Provides authentication based on endpoint aliases
and/or call signaling IP addresses with remote RADIUS servers.
It does not need any H.235 <B>tokens</B> inside RAS messages,
so it can be used on a wider range of systems as compared to <CODE>RadAuth</CODE>.
RRQ, ARQ and Q.931 Setup messages can be authenticated using this module.
See section 
<A HREF="#radaliasauth">[RadAliasAuth]</A> for details.
<P>
</LI>
<LI><CODE>SQLAuth</CODE>
<P>A powerful module to authenticate and authorize RRQ, ARQ, LRQ and Setup
messages. It can perform checks based on various parameters such as 
caller's number, destination number, username and more. It also supports
enforcing call duration limit, number rewriting, call routing, alias
verification and assignment.
See section 
<A HREF="#sqlauth">[SQLAuth]</A> for more details.
<P>
</LI>
<LI><CODE>CapacityControl</CODE>
<P>A flexible module to control inbound call volume with ability to configure
various conditions. IMPORTANT: It must be used in conjunction with the <CODE>CapacityControl</CODE>
accounting module. See section 
<A HREF="#capctrl">[CapacityControl]</A> for more details.
<P>
</LI>
</UL>
<P>You can also configure a rule to check only for specific RAS messages.
The following example configures <CODE>SimplePasswordAuth</CODE> as an optional rule
to check RRQ and ARQ. If a RRQ is not checked (does not contain
<B>tokens</B> or <B>cryptoTokens</B> fields), it is checked by <CODE>AliasAuth</CODE>.
The default is to accept all requests.
<P>
<DL>
<DT><B>Example 1:</B><DD><P><CODE>SimplePasswordAuth=alternative;RRQ,ARQ</CODE><BR>
<CODE>AliasAuth=sufficient;RRQ</CODE><BR>
</DL>
<P>The example below authenticates all calls, checking signaling Setup
message details, using the RadAliasAuth module.
<P>
<DL>
<DT><B>Example 2:</B><DD><P><CODE>RadAliasAuth=required;Setup</CODE><BR>
<CODE>default=allow</CODE>
</DL>
<P>This example checks endpoint registrations (RRQ) and call admissions (ARQ)
either by means of username/password (RadAuth) or alias/IP (RadAliasAuth).
Additionally, if the call is from an unregistered endpoint (and therefore
no RRQ or ARQ authentication has been performed), Setup message authentication
using RadAliasAuth takes place (SetupUnreg).
<P>
<DL>
<DT><B>Example 3:</B><DD><P><CODE>RadAuth=alternative;RRQ,ARQ</CODE><BR>
<CODE>RadAliasAuth=alternative;RRQ,ARQ,SetupUnreg</CODE><BR>
<CODE>default=reject</CODE>
</DL>
<P>
<H2><A NAME="fileipauth"></A> 8.2 Section [FileIPAuth]</H2>

<P>This section defines a list of IP addresses/networks which are allowed
to access gatekeeper resources. A list of allowed prefixes can be specified
together with an IP address. Supported Gatekeeper::Auth events are:
<CODE>GRQ</CODE>, <CODE>RRQ</CODE>, <CODE>LRQ</CODE>, <CODE>Setup</CODE> and <CODE>SetupUnreg</CODE>. Format
of a single entry is:
<P><CODE>IP=[allow | reject][;prefix[,prefix...]]</CODE>
<P>where IP is a single IP address, a network address (in A.B.C.D/M.M.M.M or A.B.C.D/LENGTH format) or a string <CODE>'any'</CODE> or <CODE>'*'</CODE> to match any address.
The access list can also be loaded from an external file using <CODE>include</CODE> directive. During authentication, network mask length defines a priority for each
entry, so rule 192.168.1.1=allow takes precedence over 192.168.1.0/24=reject.
<P>
<DL>
<DT><B>Example #1:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Auth]
FileIPAuth=required;RRQ,LRQ,Setup

[FileIPAuth]
192.168.1.240=reject
192.168.1.0/24=allow
192.168.2.0/255.255.255.0=allow;48,49,44
any=reject
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
<DL>
<DT><B>Example #2:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Auth]
FileIPAuth=required;Setup

[FileIPAuth]
include=/etc/gnugk/accesslist.ini

(EOF)

Contents of /etc/gnugk/accesslist.ini:

[FileIPAuth]
192.168.1.1=allow
192.168.1.100=allow
any=reject
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
<H2><A NAME="password"></A> 8.3 Section [SimplePasswordAuth]</H2>

<P>The section defines the userid and password pairs used by
<CODE>SimplePasswordAuth</CODE> module. All passwords are encrypted
using the <CODE>addpasswd</CODE> utility.
<P>Usage:
<BLOCKQUOTE><CODE>
<PRE>
addpasswd config section userid password
</PRE>
</CODE></BLOCKQUOTE>
<P>Example:
<BLOCKQUOTE><CODE>
<PRE>
addpasswd config.ini SimplePasswordAuth frank secret
</PRE>
</CODE></BLOCKQUOTE>
<P>Options:
<UL>
<LI><CODE>KeyFilled=123</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Default value to use as a padding byte during password encryption/decryption.
<P>
</LI>
<LI><CODE>CheckID=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Check if the aliases match the ID in the tokens.
<P>
</LI>
<LI><CODE>PasswordTimeout=120</CODE><BR>
Default: <CODE>-1</CODE><BR>
<P>The module <CODE>SimplePasswordAuth</CODE> and all its descendants will cache an
authenticated password. This field defines the cache timeout value in seconds.
<CODE>0</CODE> means never cache the password, while a negative value
means the cache never expires.
<P>
</LI>
<LI><CODE>DisableAlgorithm=MD5,H.235.1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Disable H.235 authentication algorithms in the GRQ/GCF negotiation, otherwise all algorithms supported by GnuGk are used.
A disabled algorithm will still be used if it is used by an endpoint without negotiation.
This switch can be used to avoid incompatibilities with vendor implementations.
<P>
</LI>
</UL>
<P>
<H2><A NAME="sqlpasswordauth"></A> 8.4 Section [SQLPasswordAuth]</H2>

<P>Authenticate H.235 enabled endpoints using passwords stored
in the SQL database. This section defines the SQL driver to use,
SQL database connection parameters and the query to use to retrieve passwords.
<P>
<UL>
<LI><CODE>Driver=MySQL | PostgreSQL | Firebird | ODBC | SQLite</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>SQL database driver to use. Currently, <CODE>MySQL</CODE>, <CODE>PostgreSQL</CODE>, <CODE>Firebird</CODE>, <CODE>ODBC</CODE> and <CODE>SQLite</CODE> drivers
are implemented. GnuGk supports only version 3 of SQLite.
<P>
</LI>
<LI><CODE>Host=DNS[:PORT] | IP[:PORT]</CODE><BR>
Default: <CODE>localhost</CODE><BR>
<P>SQL server host address. Can be in the form of <CODE>DNS[:PORT]</CODE> or <CODE>IP[:PORT]</CODE>.
Like <CODE>sql.mycompany.com</CODE> or <CODE>sql.mycompany.com:3306</CODE> or <CODE>192.168.3.100</CODE>.
<P>
</LI>
<LI><CODE>Database=billing</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>The database name to connect to.
<P>
</LI>
<LI><CODE>Username=gnugk</CODE><BR>
<P>The username used to connect to the database.
<P>
</LI>
<LI><CODE>Password=secret</CODE><BR>
<P>The password used to connect to the database.
If the password is not specified, a database connection attempt 
without any password will be made.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in an encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.
<P>
</LI>
<LI><CODE>CacheTimeout=120</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>This field defines how long (alias;password) pairs retrieved from the database 
will be cached in the local memory. The cache timeout value is expressed in seconds.
<CODE>0</CODE> means to not cache passwords, while a negative value
means the cache never expires (only <CODE>reload</CODE> command will refresh the cache).
<P>
</LI>
<LI><CODE>MinPoolSize=5</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Define the number of active SQL connections. This allows for better performance
under heavy load, because more than 1 concurrent query can be executed 
at the same time. Setting <CODE>MinPoolSize=1</CODE> will simulate the old behavior, 
when access to the SQL database was serialized (one query at time).
<P>
</LI>
<LI><CODE>Query=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines SQL query used to retrieve H.235 password from the database. The query
is parameterized - that means parameter replacement is made before each query
is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... strings.
Specify %% to embed a percent character before a digit into string (like <B>%%1</B>),
specify <B>%{1}</B> to allow expansion inside complex expressions like <B>%{1}123</B>.
For <CODE>SQLPasswordAuth</CODE> two parameters are defined:
<UL>
<LI><CODE>%1</CODE> - the actual alias to query the password for</LI>
<LI><CODE>%2</CODE> - the gatekeeper identifier</LI>
</UL>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
SELECT h235password FROM users WHERE alias = '%1' AND active
SELECT h235password FROM users WHERE alias = '%1' AND gk = '%2'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
</UL>
<P>
<H2><A NAME="rrqauth"></A> 8.5 Section [RasSrv::RRQAuth]</H2>

<P>Specify the action on RRQ reception (confirm or deny) for <CODE>AliasAuth</CODE> module.
The first alias (this will mostly be an H323ID) of the endpoint to
register is looked up in this section. If a parameter is found the value will
apply as a rule. A rule consists of conditions separated by "&amp;".
A registration is accepted when all conditions apply.
<P>
<DL>
<DT><B>Syntax:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
&lt;authrules&gt; :=  empty  |  &lt;authrule&gt; "&amp;" &lt;authrules&gt;

  &lt;authrule&gt;  := &lt;authtype&gt; ":" &lt;authparams&gt;
  &lt;authtype&gt;  := "sigaddr" | "sigip"
  &lt;autparams&gt; := [!&amp;]*
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>The notation and meaning of <CODE>&lt;authparams&gt;</CODE> depends on
<CODE>&lt;authtype&gt;</CODE>:
<P>
<UL>
<LI><CODE>sigaddr</CODE> - extended regular expression that has to match against the
``PrintOn(ostream)'' representation of the signal address of the request.
<P>Example:
<BLOCKQUOTE><CODE>
<PRE>
sigaddr:.*ipAddress .* ip = .* c0 a8 e2 a5 .*port = 1720.*
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>sigip</CODE> - specialized form of `<CODE>sigaddr</CODE>'.
Write the signaling IP address using (commonly used) decimal notation:
``<CODE>byteA.byteB.byteC.byteD:port</CODE>''.
<P>Example:
<BLOCKQUOTE><CODE>
<PRE>
sigip:192.168.242.165:1720
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>allow</CODE> - always accept the alias.
</LI>
<LI><CODE>deny</CODE> - always reject the alias.
</LI>
</UL>
<P>
<H2><A NAME="sqlaliasauth"></A> 8.6 Section [SQLAliasAuth]</H2>

<P>Authenticate endpoints using rules stored in the SQL database
(the rules conform to the format defined in the 
<A HREF="#rrqauth">[RasSrv::RRQAuth]</A> section). 
This section defines which SQL driver to use, SQL database connection parameters 
and the query to use to retrieve the patterns.
<P>
<UL>
<LI><CODE>Driver=MySQL | PostgreSQL | Firebird | ODBC | SQLite</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>SQL database driver to use. Currently, <CODE>MySQL</CODE>, <CODE>PostgreSQL</CODE>, <CODE>Firebird</CODE>, <CODE>ODBC</CODE> and <CODE>SQLite</CODE> drivers
are implemented.
<P>
</LI>
<LI><CODE>Host=DNS[:PORT] | IP[:PORT]</CODE><BR>
Default: <CODE>localhost</CODE><BR>
<P>SQL server host address. Can be in the form of <CODE>DNS[:PORT]</CODE> or <CODE>IP[:PORT]</CODE>.
Like <CODE>sql.mycompany.com</CODE> or <CODE>sql.mycompany.com:3306</CODE> or <CODE>192.168.3.100</CODE>.
<P>
</LI>
<LI><CODE>Database=billing</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>The database name to connect to.
<P>
</LI>
<LI><CODE>Username=gnugk</CODE><BR>
<P>The username used to connect to the database.
<P>
</LI>
<LI><CODE>Password=secret</CODE><BR>
<P>The password used to connect to the database.
If the password is not specified, a database connection attempt 
without any password will be made.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.
<P>
</LI>
<LI><CODE>CacheTimeout=120</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>This field defines how long (alias;authrule) pairs retrieved from the database 
will be cached in the local memory. The cache timeout value is expressed in seconds.
<CODE>0</CODE> means not to cache rules, while a negative value
means the cache never expires (only <CODE>reload</CODE> command will refresh the cache).
<P>
</LI>
<LI><CODE>MinPoolSize=5</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Define the number of active SQL connections. This allows for better performance
under heavy load, because more than 1 concurrent query can be executed
at the same time. Setting <CODE>MinPoolSize=1</CODE> will simulate the old behavior,
when access to the SQL database was serialized (one query at time).
<P>
</LI>
<LI><CODE>Query=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines SQL query used to retrieve alias rule from the database. The query
is parameterized - that means parameter replacement is made before each query
is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... strings.
Specify %% to embed a percent character before a digit into string (like <B>%%1</B>),
specify <B>%{1}</B> to allow expansion inside complex expressions like <B>%{1}123</B>.
For <CODE>SQLAliasAuth</CODE> two parameters are defined:
<UL>
<LI><CODE>%1</CODE> - the actual alias to query the rule for</LI>
<LI><CODE>%2</CODE> - the gatekeeper identifier</LI>
</UL>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
SELECT authrule FROM users WHERE alias = '%1' AND active
SELECT 'sigip:' || host(ip) || port FROM users WHERE alias = '%1'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
</UL>
<P>
<H2><A NAME="sqlauth"></A> 8.7 Section [SQLAuth]</H2>

<P>Authenticate and authorize endpoints/calls using a SQL database.
Support for RRQ, ARQ, LRQ and Setup events is provided.
<P>
<UL>
<LI><CODE>Driver=MySQL | PostgreSQL | Firebird | ODBC | SQLite</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>SQL database driver to use. Currently, <CODE>MySQL</CODE>, <CODE>PostgreSQL</CODE>, <CODE>Firebird</CODE>, <CODE>ODBC</CODE> and <CODE>SQLite</CODE> drivers
are implemented.
<P>
</LI>
<LI><CODE>Host=DNS[:PORT] | IP[:PORT]</CODE><BR>
Default: <CODE>localhost</CODE><BR>
<P>SQL server host address. Can be in the form of <CODE>DNS[:PORT]</CODE> or <CODE>IP[:PORT]</CODE>.
Like <CODE>sql.mycompany.com</CODE> or <CODE>sql.mycompany.com:3306</CODE> or <CODE>192.168.3.100</CODE>.
<P>
</LI>
<LI><CODE>Database=billing</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>The database name to connect to.
<P>
</LI>
<LI><CODE>Username=gnugk</CODE><BR>
<P>The username used to connect to the database.
<P>
</LI>
<LI><CODE>Password=secret</CODE><BR>
<P>The password used to connect to the database.
If the password is not specified, a database connection attempt 
without any password will be made.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.
<P>
</LI>
<LI><CODE>MinPoolSize=5</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Define the number of active SQL connections. This allows for better performance
under heavy load, because more than 1 concurrent query can be executed
at the same time. Setting <CODE>MinPoolSize=1</CODE> will simulate the old behavior,
when access to the SQL database was serialized (one query at time).
<P>
</LI>
<LI><CODE>RegQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query to be used to perform authentication and authorization
of endpoint registrations. The query is parameterized - that means parameter
replacement is made before each query is executed. The following parameters are defined:
<UL>
<LI><CODE>%g</CODE> - the gatekeeper identifier</LI>
<LI><CODE>%{gkip}</CODE> - a gatekeeper IP the request has been received on</LI>
<LI><CODE>%u</CODE> - username associated with an endpoint (usually a H.323 ID)</LI>
<LI><CODE>%{callerip}</CODE> - caller's IP (the request has been received from - NAT IP for natted endpoints)</LI>
<LI><CODE>%{aliases}</CODE> - a comma separated list of endpoint aliases</LI>
</UL>
<P>If the query returns no rows, the result is undefined, which basically
means failure for <CODE>required</CODE> rules and "try next" for optional rules.
Otherwise, the first result row is examined to determine the result of the authentication
request and to get additional information:
<OL>
<LI>The first column is converted into a boolean value (1, T, TRUE, allow, y, yes means true)
and is an authentication result (accept/reject).</LI>
<LI>If the registration is authenticated successfully, remaining columns 
are examined:
<OL>
<LI>If there exists a column called <CODE>'aliases'</CODE>, replace original endpoint
aliases with these new ones</LI>
<LI>If there exists a column called <CODE>'billingmode'</CODE>, set a billing mode
associated with the endpoint (0 - credit, </LI>
<LI>0 - debit)</LI>
<LI>If there exists a column called <CODE>'creditamount'</CODE>, set account balance
associated with the endpoint (this is an arbitrary string)</LI>
</OL>
</LI>
</OL>
<P>Query string examples:
<BLOCKQUOTE><CODE>
<PRE>
SELECT 1, 0 AS billingmode, '12.00 USD' AS creditamount
SELECT NOT disabled, assignaliases AS aliases, balance FROM users WHERE h323id = '%u'
SELECT * FROM get_registration_auth('%g', '%u', '%{callerip}', '%{aliases}') AS result(accept, aliases, billingmode, creditamount)
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>NbQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query to be used to perform authentication and authorization
of location requests sent from neighbors. The query is parameterized - that means parameter
replacement is made before each query is executed. The following parameters are defined:
<UL>
<LI><CODE>%g</CODE> - the gatekeeper identifier</LI>
<LI><CODE>%{gkip}</CODE> - a gatekeeper IP the request has been received on</LI>
<LI><CODE>%{nbid</CODE> - neighbor identifier from the config</LI>
<LI><CODE>%{nbip}</CODE> - neighbor IP (the request has been received from)</LI>
<LI><CODE>%{Calling-Station-Id}</CODE> - caller's number, if available</LI>
<LI><CODE>%{src-info}</CODE> - content of sourceInfo LRQ field, if available</LI>
<LI><CODE>%{Called-Station-Id}</CODE> - destination number</LI>
<LI><CODE>%{dest-info}</CODE> - content of destinationInfo LRQ field</LI>
<LI><CODE>%{bandwidth}</CODE> - requested bandwidth, if present in the LRQ</LI>
</UL>
<P>If the query returns no rows, the result is undefined, which basically
means failure for <CODE>required</CODE> rules and "try next" for optional rules.
Otherwise, the first result row is examined to determine the result of the authentication
and to get additional information:
<OL>
<LI>The first column is converted into a boolean value (1, T, TRUE, allow, y, yes means true)
and is an authentication result (accept/reject).</LI>
<LI>If the request is authenticated successfully, remaining columns 
are examined:
<OL>
<LI>If there exists a column called <CODE>'destination'</CODE>, populate the original
destinationInfo field with these new aliases - this may affect routing
decision, which is made after auth step.</LI>
</OL>
</LI>
</OL>
<P>Query string examples:
<BLOCKQUOTE><CODE>
<PRE>
SELECT active FROM neighbors WHERE name = '%{nbid}' AND ip = '%{nbip}' UNION SELECT 0
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>CallQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query to be used to perform authentication and authorization
of calls (ARQ and Setup). The query is parameterized - that means parameter
replacement is made before each query is executed. The following parameters are defined:
<UL>
<LI><CODE>%g</CODE> - the gatekeeper identifier</LI>
<LI><CODE>%{gkip}</CODE> - a gatekeeper IP the request has been received on</LI>
<LI><CODE>%u</CODE> - an username associated with the caller</LI>
<LI><CODE>%{callerip}</CODE> - caller's IP (the request has been received from - NAT IP for natted endpoints)</LI>
<LI><CODE>%{Calling-Station-Id}</CODE> - caller's number, if available</LI>
<LI><CODE>%{Called-Station-Id}</CODE> - destination number</LI>
<LI><CODE>%{Dialed-Number}</CODE> - original destination number (before rewrite)</LI>
<LI><CODE>%{CallId}</CODE> - H.323 call identifier (16 hex 8-bit digits)</LI>
<LI><CODE>%{bandwidth}</CODE> - requested bandwidth, if present in the ARQ</LI>
<LI><CODE>%{answer}</CODE> - 1, if the request is an answering ARQ</LI>
<LI><CODE>%{arq}</CODE> - 1 for ARQ triggered query, 0 for Setup triggered query</LI>
</UL>
<P>If the query returns no rows, the result is undefined, which basically
means failure for <CODE>required</CODE> rules and "try next" for optional rules.
Otherwise, the first result row is examined to determine the authentication
result and to get additional information:
<OL>
<LI>The first column is converted into a boolean value (1, T, TRUE, allow, y, yes means true)
and is an authentication result (accept/reject the call).</LI>
<LI>If the request is authenticated successfully, remaining columns 
are examined:
<OL>
<LI>If there exists a column called <CODE>'billingmode'</CODE>, set a billing mode
associated with the endpoint (0 - credit, </LI>
<LI>0 - debit)</LI>
<LI>If there exists a column called <CODE>'creditamount'</CODE>, set account balance
associated with the endpoint (this is an arbitrary string)</LI>
<LI>If there exists a column called <CODE>'credittime'</CODE>, use its integer
value to set call duration limit</LI>
<LI>If there exists a column called <CODE>'redirectnumber'</CODE>, replace
the original destination number with this one. You can put multiple
numbers (that correspond to multiple <CODE>'redirectip'</CODE> entries) separated
by a semicolon. You can also specify an outbound number (to be sent to a terminating gateway)
by appending it with an '=' to the rewritten number (like 485811001001=1234485811001001)</LI>
<LI>If there exists a column called <CODE>'redirectip'</CODE>, force the call
to be sent to the specified IP (one can put multiple destinations
separated by a semicolon, that will be used for failover, if failover is activated)</LI>
<LI>If there exists a column called <CODE>'proxy'</CODE>, force the gatekeeper
to enable/disable (depends on the 'proxy' column value) RTP proxy
for this call</LI>
<LI>If there exists a column called <CODE>'clientauthid'</CODE>, the gatekeeper will store
this ID in its call record and send it back on all accounting events.
This must be an unsigned integer with a maximum of 64 bits (eg. 'bigint unsigned' in MySQL).</LI>
</OL>
</LI>
<LI>If the request is denied, the remaining columns are examined:
<OL>
<LI>If there exists a column called <CODE>'q931cause'</CODE>, set a Q.931 cause in a Release Complete
to this value</LI>
<LI>If there exists a column called <CODE>'clientauthid'</CODE>, the gatekeeper will store
this ID in its call record and send it back on all accounting events.
This must be an unsigned integer with a maximum of 64 bits (eg. 'bigint unsigned' in MySQL).</LI>
</OL>
</LI>
</OL>
<P>Query string examples:
<BLOCKQUOTE><CODE>
<PRE>
SELECT 1, 360 AS credittime, 0 AS proxy
SELECT * FROM auth_call('%g', '%u', '%{Calling-Station-Id}', '%{callerip}', '%{Called-Station-Id}') AS result(accept, credittime)
SELECT 1, '1234' AS redirectnumber, '192.168.1.1' AS redirectip
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
</UL>
<P>
<P>
<H2><A NAME="prefixauth"></A> 8.8 Section [PrefixAuth]</H2>

<P>The section defines the authentication rule for the <CODE>PrefixAuth</CODE> module.
Currently, only ARQs and LRQs can be authorized by this module.
<P>First, the most specific prefix is selected according to the <B>destinationInfo</B>
field of the received request. Then the request is accepted or rejected
according to the matched rules with the most specific netmask.
If no matched prefix is found,
and the <CODE>default</CODE> option is specified, the request is accepted
or rejected according to that. Otherwise
it is rejected or passed to the next authentication module
according to the module requirement.
<P>
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
prefix=authrule[|authrule|...]
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>Syntax:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
&lt;authrule&gt; :=  &lt;result&gt; &lt;authrule&gt;

  &lt;result&gt;    := deny | allow
  &lt;authrule&gt;  := [!]ipv4:&lt;iprule&gt; | [!]alias:&lt;aliasrule&gt;
</PRE>
</CODE></BLOCKQUOTE>
</DL>

Where <CODE>&lt;iprule&gt;</CODE> can be specified in decimal dot notation or
CIDR notation, <CODE>&lt;aliasrule&gt;</CODE> is expressed in regular expression.
If the `<CODE>!</CODE>' flag precedes the rule, the sense is inverted.
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
555=deny ipv4:10.0.0.0/27|allow ipv4:0/0
5555=allow ipv4:192.168.1.1|deny ipv4:192.168.1.0/255.255.255.0
86=deny !ipv4:172.16.0.0/24
09=deny alias:^188884.*
ALL=allow ipv4:ALL
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>In this configuration, all endpoints except those from network <CODE>10.0.0.0/27</CODE>
are allowed to call prefix 555 (except 5555).
Endpoints from <CODE>192.168.1.0/24</CODE> are not allowed to call prefix 5555,
except <CODE>192.168.1.1</CODE>.
Endpoints <B>not</B> from <CODE>172.16.0.0/24</CODE> are denied to call prefix 86.
Endpoints having an alias beginning with 188884 are not allowed to call
prefix 09. All other situations are allowed.
<P>
<H2><A NAME="radauth"></A> 8.9 Section [RadAuth]</H2>

<P>This section defines configuration settings that enable
RADIUS authentication based on H.235 CATs (Cisco Access Tokens)
present in RRQ, ARQ RAS requests and Q.931 Setup messages.
<UL>
<LI><CODE>Servers=SERVER1[:AUTH_PORT[:ACCT_PORT[:SECRET]]];SERVER2[:AUTH_PORT[:ACCT_PORT[:SECRET]]];...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>RADIUS servers to be used for authentication. The list can contain an arbitrary 
number of servers. The order of servers is important, because servers will 
be queried by the RADIUS module in the given order. If no port information 
is provided, port number from <CODE>DefaultAuthPort</CODE> will be used. If no secret is set, 
the default shared secret from <CODE>SharedSecret</CODE> is taken. 
Servers names can be IP addresses or DNS names.
<P>
<DL>
<DT><B>Sample <CODE>Servers</CODE> lines:</B><DD><P><CODE>Servers=192.168.1.1</CODE><BR>
<CODE>Servers=192.168.1.1:1645</CODE><BR>
<CODE>Servers=192.168.1.1:1645:1646:secret1</CODE><BR>
<CODE>Servers=radius1.mycompany.com:1812</CODE><BR>
<CODE>Servers=radius1.mycompany.com;radius2.mycompany.com</CODE><BR>
<CODE>Servers=radius1.mycompany.com:1812:1813:secret1;radius2.mycompany.com:1812:1813:secret2</CODE><BR>
</DL>
<P>
</LI>
<LI><CODE>LocalInterface=IP_OR_FQDN</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>The specific local network interface that GnuGk should
use in order to communicate with RADIUS servers. This parameter
can be useful on NAT machines to restrict which network
interfaces are used for RADIUS communication. By default this value
is empty and allows RADIUS requests to be sent on any (best suitable)
network interface. If you are not sure what you are doing, it is
better to leave this option unset.
<P>
</LI>
<LI><CODE>RadiusPortRange=10000-11000</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>By default, GnuGk
allocates ports dynamically as specified by the operating system.
If you want to restrict which ports it should use then configure this parameter.
<P>
</LI>
<LI><CODE>DefaultAuthPort=PORT_NO</CODE><BR>
Default: <CODE>1812</CODE><BR>
<P>Default port number to be used for RADIUS authentication requests
(Access-Request packets).  Can be overridden by <CODE>Servers</CODE> attribute.
<P>
</LI>
<LI><CODE>SharedSecret=SECRET</CODE><BR>
Default: <CODE>N/A (empty string)</CODE><BR>
<P>Secret used to authenticate this GnuGk (NAS client) to RADIUS
server. It should be a cryptographically strong password. This is the default
value used if no server-specific secret is set in the <CODE>Servers</CODE> configuration option.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.
<P>
</LI>
<LI><CODE>RequestTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>2000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) for RADIUS server response to a request
sent by GnuGk. If no response is received within this time period,
the next RADIUS server is queried.
<P>
</LI>
<LI><CODE>IdCacheTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>9000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) for RADIUS request 8-bit identifiers to be
unique. If the entire 8-bit identifier range is exhausted within this period,
a new client socket (UDP socket) will be allocated by the RADIUS module. Let's
take the example: we have approximately 60 RRQs/sec - after ca. 4 seconds
8-bit identifiers range gets exhausted - new socket allocated - after next
4 seconds the second 8-bit identifiers range gets exhausted - third socket
allocated - after 9th second identifiers from the pool 1 are available again.
<P>In general, if you have too long a timeout then too many resources will be consumed.
If you have too short a timeout, then the RADIUS server may take incoming packets as duplicates
and therefore drop them.
<P>
</LI>
<LI><CODE>SocketDeleteTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>60000</CODE> (milliseconds) - 60 s<BR>
<P>Timeout for unused RADIUS sockets to be closed. It is used
in conjunction with <CODE>IdCacheTimeout</CODE> - additional sockets
created during heavy gatekeeper load periods for serving incoming
requests are closed during idle periods.
<P>
</LI>
<LI><CODE>RequestRetransmissions=NUMBER</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>How many times a single RADIUS request is transmitted to every
configured RADIUS server (if no response is received). 1 means
one transmission attempt and no re-transmission, 2 - single re-transmission, ... . Exact retransmission
method is defined by <CODE>RoundRobinServers</CODE> attribute.
<P>
</LI>
<LI><CODE>RoundRobinServers=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>RADIUS requests retransmission method.
<P>If set to 1, RADIUS request
is transmitted in the following way (until response is received):
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
<P>If set to 0, the following sequence is preserved:
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>AppendCiscoAttributes=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>If set, Cisco Vendor Specific RADIUS attributes are included
in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).
<P>
</LI>
<LI><CODE>IncludeTerminalAliases=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>If set, Cisco VSA 'h323-ivr-out' attribute is sent with a list of aliases
the endpoint is registering (RRQ.m_terminalAlias). This attribute is provided
in order to provide fine control over the list of aliases the endpoint
is allowed to register with. Format of this attribute is:
<BLOCKQUOTE><CODE>
<PRE>
        Cisco-AV-Pair = "h323-ivr-out=terminal-alias:" alias [,alias] [;]
Example:
        Cisco-AV-Pair = "h323-ivr-out=terminal-alias:helpdesk,support,77771;"
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>UseDialedNumber=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Select Called-Station-Id number type between the original one (as dialed
by the user) - <CODE>UseDialedNumber=1</CODE> - and the rewritten one - <CODE>UseDialedNumber=0</CODE>.
<P>
</LI>
</UL>
<P>
<H3>[RadAuth] Access-Request Radius Attributes</H3>

<P>For RRQs, the following RADIUS attributes are included within Access-Request packets:
<P>
<UL>
<LI><CODE>User-Name</CODE><BR>
<P>H225_RegistrationRequest.tokens[CAT].m_generalID
<P>
</LI>
<LI><CODE>CHAP-Password</CODE><BR>
<P>H225_RegistrationRequest.tokens[CAT].m_random 
+ H225_RegistrationRequest.tokens[CAT].m_challenge
<P>
</LI>
<LI><CODE>CHAP-Challenge</CODE><BR>
<P>H225_RegistrationRequest.tokens[CAT].m_timeStamp
<P>
</LI>
<LI><CODE>NAS-IP-Address</CODE><BR>
<P>GnuGk Home or a particular local network interface set
by 'LocalInterface' config parameter
<P>
</LI>
<LI><CODE>NAS-Identifier</CODE><BR>
<P>GnuGk Name
<P>
</LI>
<LI><CODE>NAS-Port-Type</CODE><BR>
<P>Virtual (GnuGk does not have concept of physical ports)
<P>
</LI>
<LI><CODE>Framed-IP-Address</CODE><BR>
<P>An IP address of registering endpoint signaling channel 
<P>
</LI>
<LI><CODE>Service-Type</CODE><BR>
<P>Login-User
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-out</CODE><BR>
<P>A list of aliases an endpoint is registering with
(only if IncludeTerminalAliases config option is set)
<P>NOTE: The list of aliases inside h323-ivr-out is in the following form:<BR>
<CODE>h323-ivr-out="h323-ivr-out=terminal-alias:alias1,alias2,...,aliasN;"</CODE><BR>
The h323-ivr-out attribute can be (in future) instantiated multiple times
inside a single Access-Request and may also contain variables other than
"terminal-alias", so a RADIUS server should be flexible enough 
with processing of this attribute.
</LI>
</UL>
<P>For ARQ and Setup messages, the following RADIUS attributes are included
inside Access-Request packets:
<P>
<UL>
<LI><CODE>User-Name</CODE><BR>
<P>ARQ.tokens[CAT].m_generalID
<P>
</LI>
<LI><CODE>CHAP-Password</CODE><BR>
<P>ARQ.tokens[CAT].m_random + ARQ.tokens[CAT].m_challenge
<P>
</LI>
<LI><CODE>CHAP-Challenge</CODE><BR>
<P>ARQ.tokens[CAT].m_timeStamp
<P>
</LI>
<LI><CODE>NAS-IP-Address</CODE><BR>
<P>GnuGk Home or a particular local network interface set
by 'LocalInterface' config parameter
<P>
</LI>
<LI><CODE>NAS-Identifier</CODE><BR>
<P>GnuGk Name
<P>
</LI>
<LI><CODE>NAS-Port-Type</CODE><BR>
<P>Virtual (GnuGk does not have concept of physical ports)
<P>
</LI>
<LI><CODE>Framed-IP-Address</CODE><BR>
<P>An IP address of registering endpoint signaling channel 
<P>
</LI>
<LI><CODE>Service-Type</CODE><BR>
<P>Login-User (for ARQs from originating endpoint)
or Call-Check (for ARQs from answering endpoint)
<P>
</LI>
<LI><CODE>Calling-Station-Id</CODE><BR>
<P>Calling party's number (if available)
<P>
</LI>
<LI><CODE>Called-Station-Id</CODE><BR>
<P>Called party's number
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-conf-id</CODE><BR>
<P>H.323 conference ID from ARQ
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-call-type</CODE><BR>
<P>Call type (fixed value: "h323-call-type=VoIP")
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-call-origin</CODE><BR>
<P>Call origin ("answer","originate")
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-gw-id</CODE><BR>
<P>The same as NAS-Identifier
</LI>
</UL>
<P>
<P>
<H3>[RadAuth] Access-Accept Radius Attributes</H3>

<P>For RRQs, the following RADIUS attributes are recognized 
inside Access-Accept packets:
<P>
<UL>
<LI><CODE>VSA: VendorId=Cisco, h323-return-code</CODE><BR>
<P>If present and not 0, the request is rejected. This check is provided 
to allow interoperability with some poor billing systems, which send 
Access-Accept with non-zero h323-return-code to reject the call instead
of Access-Reject. The attribute can be in the form h323-return-code="1" 
or h323-return-code="h323-return-code=1". Note that the return code
is a string, not an integer.
<P>
</LI>
<LI><CODE>VSA: VendorId=Cisco, h323-billing-model</CODE><BR>
<P>Billing mode for this account. Can be 0 (credit), 1 or 2 (debit). 
If an endpoint can understand H.225.0 CallCreditServiceControl messages,
this information is used to build the message.
<P>
</LI>
<LI><CODE>VSA: VendorId=Cisco, h323-credit-amount</CODE><BR>
<P>A string representing current user's account balance. If an endpoint 
can understand H.225.0 CallCreditServiceControl messages, 
this information is used to build the message.
<P>
</LI>
<LI><CODE>VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-in</CODE><BR>
<P>If present, it is scanned for 'terminal-alias' variable that can contain
a list of aliases that should be assigned to the endpoint being registered.
All RRQ aliases that do not match this list are removed.
The 'disable-codec' variable is also supported to disallow certain codecs for this call.
The 'proxy' variable that can contain 'yes' or 'no' for enabling/disabling proxy mode for this call.
The format of these attributes is as follows:
<P><CODE>Cisco-AVPair = "h323-ivr-in=variable:value;[variable:value;]"</CODE><BR>
<P>where the "variable" can be "terminal-alias":
<P>Cisco-AVPair = "h323-ivr-in=terminal-alias:alias1[,alias2,...];"
<P>
<DL>
<DT><B>Example 1:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
RRQ {
        m_terminalAlias = { "myalias", "1234" }
}

if RADIUS server returns the following h323-ivr-in:

Access-Accept {
        Cisco-AVPair = "h323-ivr-in=terminal-alias:anotheralias,6789;"
}

the endpoint will get registered with aliases "anotheralias" and "6789".
Also RCF will contain:

RCF {
        m_terminalAlias = { "anotheralias", "6789" }
}
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
<DL>
<DT><B>Example 2 (add E164 to an existing alias):</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
RRQ {
        m_terminalAlias = { "it_s_me" }
}

if RADIUS server returns the following h323-ivr-in:

Access-Accept {
        Cisco-AVPair = "h323-ivr-in=terminal-alias:it_s_me,48586259732;"
}

RCF will contain:

RCF {
        m_terminalAlias = { "it_s_me", "48586259732" }
}
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
<DL>
<DT><B>Example 3 (disable G.711 and G.729 codecs):</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
Access-Accept {
        Cisco-AVPair = "h323-ivr-in=codec-disable:g711Ulaw64k;g729;g711Alaw64k;g729AnnexA;"
}
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
<DL>
<DT><B>Example 4 (enable proxy mode):</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
Access-Accept {
        Cisco-AVPair = "h323-ivr-in=proxy:yes"
}
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
</UL>
<P>     
For ARQs, the following RADIUS attributes are recognized
within Access-Accept packets:
<P>
<UL>
<LI><CODE>VSA: VendorId=Cisco, h323-return-code</CODE><BR>
<P>If present and not 0, the request is rejected. This check is provided
to allow interoperability with some poor billing systems, that send 
Access-Accept with non-zero h323-return-code to reject the call instead 
of Access-Reject. The attribute can be in form h323-return-code="1" 
or h323-return-code="h323-return-code=1". Note that the return code
is a string, not an integer.
<P>
</LI>
<LI><CODE>VSA: VendorId=Cisco, h323-billing-model</CODE><BR>
<P>Billing mode for this account. Can be 0 (credit), 1 or 2 (debit). 
If an endpoint can understand H.225.0 CallCreditServiceControl messages,
this information is used to build the message.
<P>
</LI>
<LI><CODE>VSA: VendorId=Cisco, h323-credit-amount</CODE><BR>
<P>A string representing current user account balance. If an endpoint can 
understand H.225.0 CallCreditServiceControl messages, this information 
is used to build the message.
<P>
</LI>
<LI><CODE>VSA: VendorId=Cisco, h323-credit-time</CODE><BR>
<P>If present, it enforces maximum call duration (in seconds).
The attribute can be in form of h323-credit-time="120" 
or h323-credit-time="h323-credit-time=120". Note that the return code 
is a string, not an integer.
<P>
</LI>
<LI><CODE>Session-Timeout</CODE><BR>
<P>If present, it enforces maximum call duration (in seconds).
This is a standard RADIUS attribute of integer type.
<P>
</LI>
<LI><CODE>VSA: VendorId=Cisco, h323-redirect-ip-address</CODE><BR>
<P>If present, a call is sent to the IP address present in this attribute.
You can put multiple destinations separated with a semicolon.
<P>
</LI>
<LI><CODE>VSA: VendorId=Cisco, h323-redirect-number</CODE><BR>
<P>If present, a called station id is rewritten to this number.
You can put multiple numbers separated by a semicolon.
For each number you can also specify an outbound number (that is sent
to a terminating gateway) by appending it with a '='.
</LI>
</UL>
<P>NOTE: If both Session-Timeout and h323-credit-time are present, the smaller value
is used.
<P>NOTE: If multiple failover mechanisms are specified, eg. multiple numbers in h323-redirect-number
<B>and</B> multiple IPs in h323-redirect-ip-address, there is no guarantee that the the
first number is used for the first IP and the 2nd number for the 2nd IP.
This will usually the case, but for example when a capacity limit disables one IP,
the association will change.
<P>
<P>
<H2><A NAME="radaliasauth"></A> 8.10 Section [RadAliasAuth]</H2>

<P>This section defines configuration settings that enable
RADIUS authentication based on endpoint aliases and/or IP addresses
present in a RRQ RAS, ARQ RAS or Q.931 Setup request.
This authentication scheme is useful both for endpoints registered
at the gatekeeper (ARQ, RRQ) and calls from unregistered endpoints (Setup).
<P>
<UL>
<LI><CODE>Servers=SERVER1[:AUTH_PORT[:ACCT_PORT[:SECRET]]];SERVER2[:AUTH_PORT[:ACCT_PORT[:SECRET]]];...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>RADIUS servers to be used for RAS requests authentication.
This list can contain an arbitrary number of servers. The order of servers 
is important, because servers will be queried by the RADIUS module 
in the given order. If no port information is specified, the port number from 
<CODE>DefaultAuthPort</CODE> will be used. If no secret is set, 
the default shared secret from <CODE>SharedSecret</CODE> is used.
Servers can be IP addresses or DNS names.
<P>
<DL>
<DT><B>Example:</B><DD><P><CODE>Servers=192.168.3.1:1645;192.168.3.2:1812:1813:mysecret;radius.mycompany.com</CODE>
</DL>
<P>
</LI>
<LI><CODE>LocalInterface=IP_OR_FQDN</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Specific local network interface that GnuGk should
use in order to communicate with RADIUS servers. This parameter
can be useful on NAT machines to restrict number of network
interfaces used for RADIUS communication. By default this value
is empty and allows RADIUS requests to be sent on any (best suitable)
network interface. If you are not sure what you are doing, it is
better to leave this option unset.
<P>
</LI>
<LI><CODE>RadiusPortRange=10000-11000</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>By default (if this option is not set) RADIUS client
allocates ports dynamically as specified by the operating system.
If you want to restrict RADIUS client to use ports from
a particular range only - set this parameter.
<P>
</LI>
<LI><CODE>DefaultAuthPort=PORT_NO</CODE><BR>
Default: <CODE>1812</CODE><BR>
<P>Default port number to be used for RADIUS authentication requests
(Access-Request packets), if not overridden by <CODE>Servers</CODE> attribute.
<P>
</LI>
<LI><CODE>SharedSecret=SECRET</CODE><BR>
Default: <CODE>N/A (empty string)</CODE><BR>
<P>Secret used to authenticate this GnuGk (NAS client) to RADIUS
server. It should be a cryptographically strong password. This is the default
value used, if no server-specific secret is set in the <CODE>Servers</CODE>.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.
<P>
</LI>
<LI><CODE>RequestTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>2000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) for RADIUS server response to a request
sent by GnuGk. If no response is received within this time period,
next RADIUS server is queried.
<P>
</LI>
<LI><CODE>IdCacheTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>9000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) for RADIUS request 8-bit identifiers to be
unique. If all 8-bit identifier range is exhausted within this period,
new client socket (UDP socket) is allocation by RADIUS module. Let's
take the example: we have approximately 60 RRQs/sec - after ca. 4 seconds
8-bit identifiers range gets exhausted - new socket allocated - after next
4 seconds the second 8-bit identifiers range gets exhausted - third socket
allocated - after 9th second identifiers from the pool 1 are available again
- ... . In general, too long timeout - too much resources consumed,
too short timeout - RADIUS server may take incoming packets as duplicated
and therefore drop it.
<P>
</LI>
<LI><CODE>SocketDeleteTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>60000</CODE> (milliseconds) - 60 s<BR>
<P>Timeout for unused RADIUS sockets to be closed. It is used
in conjunction with <CODE>IdCacheTimeout</CODE> - additional sockets
created during heavy gatekeeper load periods for serving incoming
requests are closed during idle periods.
<P>
</LI>
<LI><CODE>RequestRetransmissions=NUMBER</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>How many times a single RADIUS request is transmitted to every
configured RADIUS server (if no response is received). 1 means
no retransmission, 2 - single retransmission, ... . Exact retransmission
method is defined by <CODE>RoundRobinServers</CODE> attribute.
<P>
</LI>
<LI><CODE>RoundRobinServers=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>RADIUS requests retransmission method.
<P>If set to 1, RADIUS request
is transmitted in the following way (until response is received):
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
<P>If set to 0, the following sequence is preserved:
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>AppendCiscoAttributes=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>If set, Cisco Vendor Specific RADIUS attributes are included
in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).
<P>
</LI>
<LI><CODE>IncludeTerminalAliases=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>If set, Cisco VSA 'h323-ivr-out' attribute is sent with a list of aliases
the endpoint is registering (RRQ.m_terminalAlias). This attribute is provided
in order to provide fine control over the list of aliases the endpoint
is allowed to register with. Format of this attribute is:
<BLOCKQUOTE><CODE>
<PRE>
        Cisco-AV-Pair = "h323-ivr-out=terminal-alias:" alias [,alias] [;]
Example:
        Cisco-AV-Pair = "h323-ivr-out=terminal-alias:helpdesk,support,77771;"
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>FixedUsername</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If this parameter is set, it overwrites a value of User-Name RADIUS attribute
for outgoing RADIUS request. That means every Access-Request will be
authenticated as for user <CODE>FixedUsername</CODE>.
<P>
</LI>
<LI><CODE>FixedPassword</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If not set, User-Password is a copy of User-Name. For example, if User-Name
is 'john' then User-Password will also be set to 'john'. Setting this
parameter overrides this behavior and User-Password attribute will be
always set to the value of <CODE>FixedPassword</CODE>.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.
<P>
<DL>
<DT><B>Example 1:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
(Neither FixedUsername nor FixedPassword set)
</PRE>
</CODE></BLOCKQUOTE>

All endpoints will be authenticated using their alias as the username
and the password. That means, for example, endpoint 'EP1' will be authenticated
with the username 'EP1 and the password 'EP1'.
</DL>
<P>
<DL>
<DT><B>Example 2:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
(FixedUsername not set)
FixedPassword=ppp
</PRE>
</CODE></BLOCKQUOTE>

All endpoints will be authenticated using their alias and the password 'ppp'.
</DL>
<P>
<DL>
<DT><B>Example 3:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
FixedUsername=ppp
FixedPassword=ppp
</PRE>
</CODE></BLOCKQUOTE>

All endpoints will be authenticated using the username 'ppp'
and the password 'ppp'.
</DL>
<P>
</LI>
<LI><CODE>UseDialedNumber=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Select Called-Station-Id number type between the original one (as dialed
by the user) - <CODE>UseDialedNumber=1</CODE> - and the rewritten one - <CODE>UseDialedNumber=0</CODE>.
<P>
</LI>
</UL>
<P>
<H3>[RadAliasAuth] Access-Request Radius Attributes</H3>

<P>For RRQs, the same attributes as with RadAuth are sent, with an exception
of username/password attributes (CHAP-Password, CHAP-Challenge, User-Name):
<P>
<UL>
<LI><CODE>User-Name</CODE><BR>
<P>Either an endpoint alias from RRQ or a value of FixedUsername 
config parameter. If no alias is present, an IP address is used
<P>
</LI>
<LI><CODE>User-Password</CODE><BR>
<P>Either the same as User-Name or a value of FixedPassword
config parameter
</LI>
</UL>
<P>For ARQ and Setup messages, the same attributes as with RadAuth are sent,
with an exception of username/password attributes (CHAP-Password, 
CHAP-Challenge, User-Name):
<P>
<UL>
<LI><CODE>User-Name</CODE><BR>
<P>Either an endpoint alias or a value of FixedUsername config parameter
<P>
</LI>
<LI><CODE>User-Password</CODE><BR>
<P>Either the same as User-Name or a value of FixedPassword config parameter
</LI>
</UL>
<P>
<P>
<H3>[RadAliasAuth] Access-Accept Radius Attributes</H3>

<P>Exactly the same attributes are recognized as with RadAuth module.
<P>
<P>
<H2><A NAME="capctrl"></A> 8.11 Section [CapacityControl]</H2>

<P>This section contains a set of rules for controlling inbound call volume
depending on various conditions. In order for this module to work, CapacityControl
authentication and accounting modules have to be enabled like this:
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Auth]
CapacityControl=required;Setup
 
[Gatekeeper::Acct]
CapacityControl=required;start,stop
</PRE>
</CODE></BLOCKQUOTE>
<P>A capacity rule can be matched by a caller's IP, caller's H.323 ID and/or
caller's number (CLI) - in the order specified. In addition, the match can
be narrowed by specifying a called number pattern. This module works by keeping
lists of current call volume for each inbound route (rule) - this is done
by having <CODE>CapacityControl</CODE> accounting module configured to add/remove
active calls from matching routes. The <CODE>CapacityControl</CODE> authentication module
checks rules and accepts/rejects a call based on current/max call volume
for a matching inbound route.
<P>
<DL>
<DT><B>Format for an inbound route rule:</B><DD><P><CODE>[ip:CALLER_IP|h323id:CALLER_H323ID|cli:CALLER_NUMBER]=[CALLED NUMBER REGEX PATTERN] MAX_CAPACITY</CODE>
<P><CODE>ip:</CODE>, <CODE>h323id:</CODE> and <CODE>cli:</CODE> prefixes define rule type. An inbound call
will be matched either by caller's IP, H.323ID or CLI. The optional <CODE>CALLED NUMBER REGEX PATTERN</CODE>
is a regular expression that the called number should match to apply this rule to.
<CODE>MAX_CAPACITY</CODE> is maximum number of active calls for this route.
<P>The rules are match in the following order:
<UL>
<LI>IP rules</LI>
<LI>H.323ID rules</LI>
<LI>CLI rules</LI>
</UL>
<P>The longest match in the first matching category is used.
<P>
<DT><B>Example 1:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[CapacityControl]
ip:192.168.1.0/24=30
ip:any=120
</PRE>
</CODE></BLOCKQUOTE>
<P>These rules tell that the 192.168.1.0/24 subnet can send up to 30 concurrent
calls, while all other IPs can send up to 120 concurrent calls.
<P>
<DT><B>Example 2:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[CapacityControl]
%r1% cli:1001=30
%r2% cli:1001=^48(50|51) 5
</PRE>
</CODE></BLOCKQUOTE>
<P>These rules limit caller with CLI 1001 to send up to 5 calls to 4850/4851
destinations and up to 30 calls to other destinations. %r1% and %r2% are
special constructs to allow having the same <CODE>cli:1001</CODE> config key more
than once.
</DL>
<P>
<P>
<H2>8.12 Section [GkH350::Settings]</H2>

<P>WARNING: This is an experimental feature and not tested very well.
<P>This section defines the LDAP server and standard H.350 directory operating
parameters to be used.
<P>
<UL>
<LI><CODE>ServerName</CODE><BR>
Default: <CODE>127.0.0.1</CODE>
<P>The LDAP server IP address.
<P>
</LI>
<LI><CODE>ServerPort</CODE><BR>
Default: <CODE>389</CODE>
<P>The LDAP server's TCP port (usually 389).
<P>
</LI>
<LI><CODE>SearchBaseDN</CODE><BR>
Default: <CODE>N/A</CODE>
<P>Entry point into the server's H.350 directory structure.
Searches are only made below this root node.
<P>
</LI>
<LI><CODE>BindUserDN</CODE><BR>
Default: <CODE>N/A</CODE>
<P>The distinguished name the gatekeeper uses to bind
to the LDAP server. Leave empty if you want to access
the LDAP server anonymously.
<P>
</LI>
<LI><CODE>BindUserPW</CODE><BR>
Default: <CODE>N/A</CODE>
<P>If you specified <CODE>BindUserDN</CODE>, then specify the corresponding
password to be used for binding here.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in an encrypted form and should be created 
using the <CODE>addpasswd</CODE> utility.
<P>
</LI>
<LI><CODE>BindAuthMode</CODE><BR>
Default: <CODE>simple</CODE>
<P>Bind Authentication method choices are <CODE>simple,sasl,kerberos</CODE>
<P>
</LI>
<LI><CODE>ServiceControl=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Use RRQ/RCF service control field to advise an endpoint of the H.350 directory 
and searchDN to use for white page lookups.
<P>
</LI>
<LI><CODE>AssignedAliases=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Use H.350.1 to advise endpoints of their assigned aliases.
<P>
</LI>
<LI><CODE>GatekeeperDiscovery=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Use H.350.1 to resolve on GRQ/GCF the registering endpoints assigned gatekeeper 
(h323IdentityGKDomain).
<P>
</LI>
</UL>
<P>
<H2><A NAME="s9">9. Accounting Configuration</A></H2>

<P>The following sections in the config file can be used to configure accounting.
<P>
<H2><A NAME="gkacct"></A> 9.1 Section [Gatekeeper::Acct]</H2>

<P>This section defines a list of modules which may be used to perform
accounting.  The accounting function can be used for logging gatekeeper
on/off events and call start/stop/update events.  Each accounting module
logs received events to module-specific storage.  The various storage
options include plain text file, RADIUS server and many more.  The
configuration is very similar to the one for gatekeeper authentication (see
<A HREF="#gkauth">[Gatekeeper::Auth]</A>).
<P>All CDRs are also sent to the status port and can be used by external applications.
<P>
<DL>
<DT><B>Syntax:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
acctmod=actions

 &lt;acctmod> := FileAcct | RadAcct | SQLAcct | StatusAcct | SyslogAcct | CapacityControl | ...
 &lt;actions> := &lt;control>[;&lt;event>,&lt;event>,...]
 &lt;control> := optional | required | sufficient | alternative
 &lt;event>   := start | stop | alert | connect | update | register | unregister | on | off
</PRE>
</CODE></BLOCKQUOTE>
</DL>

The event list tells the gatekeeper which events should trigger logging
with the given accounting module (if an event type is supported by the module):
<UL>
<LI><CODE>start</CODE> - a call has been started and a Setup message has been received (only available in routed mode)</LI>
<LI><CODE>alert</CODE> - a call is alerting (only available in routed mode)</LI>
<LI><CODE>connect</CODE> - a call has been connected (only available in routed mode)</LI>
<LI><CODE>update</CODE> - a call is active and a periodic update is performed
to reflect the new call duration. The frequency of these updates is determined
by the <B>AcctUpdateInterval</B> variable from the 
<A HREF="#calltable">[CallTable]</A>
section</LI>
<LI><CODE>register</CODE> - an endpoint has registered</LI>
<LI><CODE>unregister</CODE> - an endpoint has unregistered</LI>
<LI><CODE>stop</CODE> - a call has been disconnected (removed from the gatekeeper call table)</LI>
<LI><CODE>on</CODE> - the gatekeeper has been started</LI>
<LI><CODE>off</CODE> - the gatekeeper has been shut down</LI>
</UL>

An event logged by a module may results in one of three result codes:
<B>ok</B>, <B>fail</B>, <B>next</B>.
<UL>
<LI><CODE>ok</CODE> - the event has been logged successfully by this module</LI>
<LI><CODE>fail</CODE> - the module failed to log the event</LI>
<LI><CODE>next</CODE> - the event has not been logged by this module, because the module
is not configured for/does not support this event type</LI>
</UL>

Accounting modules can be stacked to log events by multiple modules or to create
failover setups. The <B>control</B> flag for each module, along with result codes,
define what is the final status of the event processing by the entire module stack.
If the final result is <B>failure</B>, some special actions may take place. Currently,
if a call <B>start</B> event logging fails, the call is disconnected immediately.
The following <B>control</B> flags are recognized:
<UL>
<LI><CODE>required</CODE> - if the module fails to log an event, the final status
is set to failure and the event is passed down to any remaining
modules.</LI>
<LI><CODE>optional</CODE> - the module tries to log an event, but the final status
is not affected by success or failure (except when the module
is last on the list). The event is always passed down
to any remaining modules.</LI>
<LI><CODE>sufficient</CODE> - the module determines the final status. If an event
is logged successfully, no remaining modules are processed.
Otherwise the final status is set to failure and the event
is passed down to any remaining modules.</LI>
<LI><CODE>alternative</CODE> - if the module logs an event successfully, no remaining
modules are processed. Otherwise the final status is
not modified and the event is passed down to any remaining
modules.</LI>
</UL>
<P>Currently supported accounting modules:
<UL>
<LI><CODE>FileAcct</CODE>
<P>A plain Call Detail Report ("CDR") text file logger. It outputs CDR status data to
a specified text file. This module only supports the <B>stop</B> accounting event.
Configuration settings are read from 
<A HREF="#fileacct">[FileAcct]</A> section.
<P>
</LI>
<LI><CODE>RadAcct</CODE>
<P>This module performs RADIUS accounting. It supports the event types
start, stop, update, on, off.
See section 
<A HREF="#radacct">[RadAcct]</A> for configuration details.
<P>
</LI>
<LI><CODE>SQLAcct</CODE>
<P>This module performs direct SQL accounting. It supports (start, connect, stop, update)
event types. 
See section 
<A HREF="#sqlacct">[SQLAcct]</A> for configuration details.
<P>
</LI>
<LI><CODE>StatusAcct</CODE>
<P>This module logs all accounting events on the status port. It can be used to interface to external application in real-time. It supports (start, connect, stop, update)
event types. 
See section 
<A HREF="#statusacct">[StatusAcct]</A> for configuration details.
<P>
</LI>
<LI><CODE>SyslogAcct</CODE>
<P>This module logs all accounting events to the Unix syslog. It supports (start, connect, stop, update)
event types. 
See section 
<A HREF="#syslogacct">[SyslogAcct]</A> for configuration details.
<P>
</LI>
<LI><CODE>CapacityControl</CODE>
<P>This module performs inbound call volume logging, required for the <CODE>CapacityControl</CODE>
authentication module to work correctly. See the section 
<A HREF="#capctrl">[CapacityControl]</A>
for details.
<P>
</LI>
<LI><CODE>default</CODE>
<P>This is a special pseudo module - it is used to set the final status
if other modules have not determined it. The format is as follows:
<DL>
<DT><B>Syntax:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
 default=&lt;status>[;&lt;event>,&lt;event>,...]
 &lt;status> := accept | fail
 &lt;event>  := start | stop | alert | connect | update | register | unregister | on | off
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
</UL>
<P>Sample configuration #1 (try to log call start/stop with RADIUS server,
and always write a CDR to a text file):
<DL>
<DT><B>Example:</B><DD><P><CODE>RadAcct=optional;start,stop</CODE><BR>
<CODE>FileAcct=required</CODE><BR>
</DL>
<P>Sample configuration #2 (try to log call start/stop with RADIUS server,
if it fails use a CDR log file):
<DL>
<DT><B>Example:</B><DD><P><CODE>RadAcct=alternative;start,stop</CODE><BR>
<CODE>FileAcct=sufficient;stop</CODE><BR>
<CODE>default=accept</CODE><BR>
</DL>

The <B>default</B> rule is required here to prevent calls from being rejected
because of RadAcct start event logging failure. If RadAcct responds with a <B>fail</B>
return code, it is passed down to the FileAcct module. The FileAcct module does not
support <B>start</B> events, so it returns a <B>next</B> code. If there were
no <B>default</B> rule, the final status would be failure, because no module
has been able to log the event.
<P>Sample configuration #3 (always log call start and stop events with RADIUS
server, if it fails for call stop event, use a CDR file to store call info):
<DL>
<DT><B>Example:</B><DD><P><CODE>RadAcct=alternative;start,stop</CODE><BR>
<CODE>FileAcct=sufficient;stop</CODE><BR>
<CODE>default=fail;start</CODE><BR>
</DL>

The <B>default</B> rule is optional here. If RadAcct returns a <B>fail</B>
code for the <B>start</B> event, the code is passed to the FileAcct module.
The FileAcct module does not support <B>start</B> events, so it returns <B>next</B>
return code. The <B>default</B> rule ensures that the call is disconnected
if the call start event could not be logged with RadAcct. However, we still want
to store a CDR in a text file in case the RADIUS server is down when the call
disconnects, so we can fetch call duration into a billing system later.
<P>
<H2><A NAME="fileacct"></A> 9.2 Section [FileAcct]</H2>

<P>This accounting module writes CDR lines to a specified text file. The CDR
format can be a standard one (the same as displayed by the status interface)
or a customized one (using parametrized query string).
<P>
<UL>
<LI><CODE>DetailFile=FULL_PATH_AND_FILENAME</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>A full path to the CDR plain text file. If a file with the given name already 
exists, new CDRs will be appended at the end of the file.
<P>
</LI>
<LI><CODE>StandardCDRFormat=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Use a CDR format compatible with the status interface CDR format (<CODE>1</CODE>)
or build a custom CDR string from the <B>CDRString</B> parametrized string.
<P>The StandardCDRFormat is equivalent to this definition:
<DL>
<P><CODE>TimestampFormat=RFC822</CODE><BR>
<CODE>CDRString=CDR|%n|%{CallId}|%d|%{connect-time}|%{disconnect-time}|%{caller-ip}:%{caller-port}|%{caller-epid}|%{callee-ip}:%{callee-port}|%{callee-epid}|%{dest-info}|%{src-info}|%g;</CODE><BR>
</DL>
<P>
</LI>
<LI><CODE>CDRString=%s|%g|%u|%{Calling-Station-Id}|%{Called-Station-Id}|%d|%c</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If <B>StandardCDRFormat</B> is disabled (0) or not specified at all, 
this parametrized string instructs the gatekeeper on how to build a custom
CDR. Parameters are specified using <CODE>%</CODE> character and can be one letter
(like <CODE>%n</CODE>) or longer (like <CODE>%{CallId}</CODE>). Any remaining characters that
are not parameter names are simply copied to the final CDR string. The following
parameters are recognized:
<UL>
<LI><CODE>%g</CODE> - gatekeeper name</LI>
<LI><CODE>%n</CODE> - call number (not unique after gatekeeper restart)</LI>
<LI><CODE>%d</CODE> - call duration (seconds)</LI>
<LI><CODE>%t</CODE> - total call duration (from Setup to Release Complete)</LI>
<LI><CODE>%c</CODE> - Q.931 disconnect cause (decimal integer) as originally received</LI>
<LI><CODE>%{cause-translated}</CODE> - Q.931 disconnect cause (decimal integer) after translation rules</LI>
<LI><CODE>%r</CODE> - who disconnected the call (-1 - unknown, 0 - the gatekeeper, 1 - the caller, 2 - the callee)</LI>
<LI><CODE>%p</CODE> - PDD (Post Dial Delay) in seconds</LI>
<LI><CODE>%s</CODE> - unique (for this gatekeeper) session identifier (Acct-Session-Id)</LI>
<LI><CODE>%u</CODE> - H.323 ID of the calling party</LI>
<LI><CODE>%{gkip}</CODE> - IP address of the gatekeeper</LI>
<LI><CODE>%{CallId}</CODE> - H.323 call identifier (16 hex 8-bit digits)</LI>
<LI><CODE>%{ConfId}</CODE> - H.323 conference identifier (16 hex 8-bit digits)</LI>
<LI><CODE>%{CallLink}</CODE> - Linked H.323 conference identifier (billing account for H.450 call transfer)</LI>
<LI><CODE>%{setup-time}</CODE> - timestamp string for Q.931 Setup message</LI>
<LI><CODE>%{alerting-time}</CODE> - timestamp string for Q.931 Alerting message</LI>
<LI><CODE>%{connect-time}</CODE> - timestamp string for a call connected event</LI>
<LI><CODE>%{disconnect-time}</CODE> - timestamp string for a call disconnect event</LI>
<LI><CODE>%{ring-time}</CODE> - time a remote phone was ringing for (from Alerting till Connect or Release Complete)</LI>
<LI><CODE>%{caller-ip}</CODE> - signaling IP address of the caller</LI>
<LI><CODE>%{caller-port}</CODE> - signaling port of the caller</LI>
<LI><CODE>%{callee-ip}</CODE> - signaling IP address of the called party</LI>
<LI><CODE>%{callee-port}</CODE> - signaling port of the called party</LI>
<LI><CODE>%{src-info}</CODE> - a colon separated list of source aliases</LI>
<LI><CODE>%{dest-info}</CODE> - a colon separated list of destination aliases</LI>
<LI><CODE>%{Calling-Station-Id}</CODE> - calling party number</LI>
<LI><CODE>%{Called-Station-Id}</CODE> - called party number (rewritten)</LI>
<LI><CODE>%{Dialed-Number}</CODE> - dialed number (as received from the calling party)</LI>
<LI><CODE>%{caller-epid}</CODE> - endpoint identifier of the calling party</LI>
<LI><CODE>%{callee-epid}</CODE> - endpoint identifier of the called party</LI>
<LI><CODE>%{call-attempts}</CODE> - number of attempts to establish the calls (with failover this can be > 1)</LI>
<LI><CODE>%{last-cdr}</CODE> - is this the last CDR for this call ? (0 / 1) only when using failover this can be 0</LI>
<LI><CODE>%{media-oip}</CODE> - caller's RTP media IP (only for H.245 routed/tunneled calls)</LI>
<LI><CODE>%{codec}</CODE> - audio codec used during the call (only for H.245 routed/tunneled calls)</LI>
<LI><CODE>%{bandwidth}</CODE> - bandwidth for this call</LI>
<LI><CODE>%{client-auth-id}</CODE> - an ID provided to GnuGk when authenticating the call (through SqlAuth)</LI>
</UL>
<BR>
<P>
</LI>
<LI><CODE>TimestampFormat=Cisco</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Format of timestamp strings printed in CDR strings. If this setting
is not specified, the global one from the main gatekeeper section is used.
<P>
</LI>
<LI><CODE>Rotate=hourly | daily | weekly | monthly | L... | S...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If set, the CDR file will be rotated based on this setting. Hourly rotation
enables rotation once per hour, daily - once per day, weekly - once per week
and monthly - once per month. An exact rotation moment is determined by a combination
of RotateDay and RotateTime. During rotation, an existing file is renamed 
to CURRENT_FILENAME.YYYYMMDD-HHMMSS, where YYYYMMDD-HHMMSS is replaced with 
the current timestamp, and new CDRs are logged to an empty file.<BR>
In addition, rotation per number of CDRs written (L...) and per file size (S...)
is supported. The <CODE>L</CODE> prefix specifies a number of CDR lines written,
the <CODE>S</CODE> prefix specifies CDR file size. <CODE>k</CODE> and <CODE>m</CODE> suffixes can
be used to specify thousands (kilobytes) and millions (megabytes). 
<P>
<DL>
<DT><B>Example 1 - no rotation:</B><DD><P><CODE>[FileAcct]</CODE><BR>
<CODE>DetailFile=/var/log/gk/cdr.log</CODE><BR>
</DL>
<P>
<DL>
<DT><B>Example 2 - rotate every hour (00:45, 01:45, ..., 23:45):</B><DD><P><CODE>[FileAcct]</CODE><BR>
<CODE>DetailFile=/var/log/gk/cdr.log</CODE><BR>
<CODE>Rotate=hourly</CODE><BR>
<CODE>RotateTime=45</CODE><BR>
</DL>
<P>
<DL>
<DT><B>Example 3 - rotate every day at 23:00 (11PM):</B><DD><P><CODE>[FileAcct]</CODE><BR>
<CODE>DetailFile=/var/log/gk/cdr.log</CODE><BR>
<CODE>Rotate=daily</CODE><BR>
<CODE>RotateTime=23:00</CODE><BR>
</DL>
<P>
<DL>
<DT><B>Example 4 - rotate every Sunday at 00:59:</B><DD><P><CODE>[FileAcct]</CODE><BR>
<CODE>DetailFile=/var/log/gk/cdr.log</CODE><BR>
<CODE>Rotate=weekly</CODE><BR>
<CODE>RotateDay=Sun</CODE><BR>
<CODE>RotateTime=00:59</CODE><BR>
</DL>
<P>
<DL>
<DT><B>Example 5 - rotate on the last day of each month:</B><DD><P><CODE>[FileAcct]</CODE><BR>
<CODE>DetailFile=/var/log/gk/cdr.log</CODE><BR>
<CODE>Rotate=monthly</CODE><BR>
<CODE>RotateDay=31</CODE><BR>
<CODE>RotateTime=23:00</CODE><BR>
</DL>
<P>
<DL>
<DT><B>Example 6 - rotate per every 10000 CDRs:</B><DD><P><CODE>[FileAcct]</CODE><BR>
<CODE>DetailFile=/var/log/gk/cdr.log</CODE><BR>
<CODE>Rotate=L10000</CODE><BR>
</DL>
<P>
<DL>
<DT><B>Example 7 - rotate per every 10 kilobytes:</B><DD><P><CODE>[FileAcct]</CODE><BR>
<CODE>DetailFile=/var/log/gk/cdr.log</CODE><BR>
<CODE>Rotate=S10k</CODE><BR>
</DL>
<P>
</LI>
</UL>
<P>
<H2><A NAME="radacct"></A> 9.3 Section [RadAcct]</H2>

<P>This accounting module sends accounting data to a RADIUS server. Module
configuration is almost the same as for RADIUS authenticators (see
<A HREF="#radauth">[RadAuth]</A> and 
<A HREF="#radaliasauth">[RadAliasAuth]</A>
for more details on the parameters).
<P>
<UL>
<LI><CODE>Servers=SERVER1[:AUTH_PORT:ACCT_PORT[:SECRET]];SERVER2[:AUTH_PORT:ACCT_PORT[:SECRET]];...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>RADIUS servers to send accounting data to. If no port information is given,
a port number from <CODE>DefaultAcctPort</CODE> is be used. If no secret is set, 
the default shared secret from <CODE>SharedSecret</CODE> is used. Server names may be
specified by IP address or DNS name.
<P>
<DL>
<DT><B>Sample <CODE>Servers</CODE> lines:</B><DD><P><CODE>Servers=192.168.1.1</CODE><BR>
<CODE>Servers=192.168.1.1:1645:1646</CODE><BR>
<CODE>Servers=192.168.1.1:1645:1646:secret1</CODE><BR>
<CODE>Servers=radius1.mycompany.com:1812:1813</CODE><BR>
<CODE>Servers=radius1.mycompany.com;radius2.mycompany.com</CODE><BR>
<CODE>Servers=radius1.mycompany.com:1812:1813:secret1;radius2.mycompany.com:1812:1813:secret2</CODE><BR>
</DL>
<P>
</LI>
<LI><CODE>LocalInterface=IP_OR_FQDN</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Specific local network interface that 
<A HREF="http://www.gnugk.org/">GnuGk</A> should
use in order to communicate with RADIUS servers.
<P>
</LI>
<LI><CODE>RadiusPortRange=10000-11000</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>By default (if this option is not set) GnuGk 
allocates ports dynamically as specified by the operating system.
In order to restrict the ports which GnuGk will use then configure this parameter appropriately.
<P>
</LI>
<LI><CODE>DefaultAcctPort=PORT_NO</CODE><BR>
Default: <CODE>1813</CODE><BR>
<P>Default port number to be used for RADIUS accounting requests.
May be overridden by the <CODE>Servers</CODE> attribute.
<P>
</LI>
<LI><CODE>SharedSecret=SECRET</CODE><BR>
Default: <CODE>N/A (empty string)</CODE><BR>
<P>A secret used to authenticate this GnuGk (NAS client) to a RADIUS
server. It should be a cryptographically strong password. This is the default
value used if no server-specific secret is set in the <CODE>Servers</CODE>.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.
<P>
</LI>
<LI><CODE>RequestTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>2000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) for a RADIUS server response to a request
sent by GnuGk. If no response is received within this time period,
then the next RADIUS server is queried.
<P>
</LI>
<LI><CODE>IdCacheTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>9000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) for RADIUS request 8-bit identifiers to be
unique.
<P>
</LI>
<LI><CODE>SocketDeleteTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>60000</CODE> (milliseconds) - 60 s<BR>
<P>Timeout for unused RADIUS sockets to be closed.
<P>
</LI>
<LI><CODE>RequestRetransmissions=NUMBER</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>How many times a single RADIUS request is transmitted to every
configured RADIUS server (if no response is received).
<P>
</LI>
<LI><CODE>RoundRobinServers=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>RADIUS requests retransmission method.
<P>If set to 1, RADIUS request
is transmitted in the following way (until response is received):
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
<P>If set to 0, the following sequence is preserved:
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>AppendCiscoAttributes=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>If set, Cisco Vendor Specific RADIUS attributes are included
in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).
<P>
</LI>
<LI><CODE>TimestampFormat=ISO8601</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Format of timestamp strings sent in RADIUS attributes. If this setting
is not specified, the global one from the main gatekeeper section is applied.
<P>
</LI>
<LI><CODE>UseDialedNumber=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Select Called-Station-Id number type between the original one (as dialed
by the user) - <CODE>UseDialedNumber=1</CODE> - and the rewritten one - <CODE>UseDialedNumber=0</CODE>.
<P>
</LI>
</UL>
<P>
<P>
<H3>[RadAcct] Accounting-Request RADIUS Attributes</H3>

<P>For an Accounting-Request, the following RADIUS attributes are included
within Accounting-Request packets. Each attribute 
is followed by a list of accounting event types.
<P>
<UL>
<LI><CODE>Acct-Status-Type (start,update,stop,on,off)</CODE><BR>
<P>The accounting event type (Start, Interim-Update, Stop, 
Accounting-On, Accounting-Off).
<P>
</LI>
<LI><CODE>NAS-IP-Address (start,update,stop,on,off)</CODE><BR>
<P>An IP address of the gatekeeper.
<P>
</LI>
<LI><CODE>NAS-Identifier (start,update,stop,on,off)</CODE><BR>
<P>The gatekeeper identifier (Name= gk parameter).
<P>
</LI>
<LI><CODE>NAS-Port-Type (start,update,stop,on,off)</CODE><BR>
<P>Fixed value Virtual.
<P>
</LI>
<LI><CODE>Service-Type (start,update,stop)</CODE><BR>
<P>Fixed value Login-User.
<P>
</LI>
<LI><CODE>Acct-Session-Id (start,update,stop)</CODE><BR>
<P>A unique accounting session identifier string.
<P>
</LI>
<LI><CODE>User-Name (start,update,stop)</CODE><BR>
<P>Calling party's account name.
<P>
</LI>
<LI><CODE>Framed-IP-Address (start,update,stop)</CODE><BR>
<P>An IP address for the calling party. Either an endpoint call signaling
address or a remote socket address for the signaling channel.
<P>
</LI>
<LI><CODE>Acct-Session-Time (update,stop)</CODE><BR>
<P>Call duration (seconds) - for interim-update events this is the actual
duration.
<P>
</LI>
<LI><CODE>Calling-Station-Id (start,update,stop)</CODE><BR>
<P>Calling party's number.
<P>
</LI>
<LI><CODE>Called-Station-Id (start,update,stop)</CODE><BR>
<P>Called party's number.
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-gw-id (start,update,stop)</CODE><BR>
<P>The same as NAS-Identifier.
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-conf-id (start,update,stop)</CODE><BR>
<P>H.323 Conference ID for the call.
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-call-origin (start,update,stop)</CODE><BR>
<P>Fixed string "proxy".
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-call-type (start,update,stop)</CODE><BR>
<P>Fixed string "VoIP".
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-setup-time (start,update,stop)</CODE><BR>
<P>Timestamp when the Q.931 Setup message has been received by the gk.
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-connect-time (update,stop)</CODE><BR>
<P>Timestamp when the call has been connected (Q.931 Setup message 
has been received or ACF has been sent in direct signaling mode).
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-disconnect-time (stop)</CODE><BR>
<P>Timestamp when the call has been disconnected (ReleaseComplete or DRQ
has been received).
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-disconnect-cause (stop)</CODE><BR>
<P>Q.931 two digit hexadecimal disconnect cause.
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, h323-remote-address (start,update,stop)</CODE><BR>
<P>An IP address of the called party (if known).
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-out (start, update, stop)</CODE><BR>
<P>h323-call-id variable that contains an H.323 Call Identifier.
The syntax is as follows: "h323-ivr-out=h323-call-id:123FDE 12348765 9abc1234 12".
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-out (start, update, stop)</CODE><BR>
<P>rewritten-e164-num contains the rewritten called party's number
(independent of the setting of the UseDialedNumber switch).
<P>
</LI>
<LI><CODE>Acct-Delay-Time (start,update,stop)</CODE><BR>
<P>Amount of time (seconds) the gatekeeper is trying to send the request.
Currently always 0.
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, h323_rtp_proxy (stop)</CODE><BR>
<P>Proxy mode of call (0=off, 1=on)
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTP_source_IP (stop)</CODE><BR>
<P>RTCP source report data
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTP_destination_IP (stop)</CODE><BR>
<P>RTCP source report data
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_source_packet_count (stop)</CODE><BR>
<P>RTCP source report data
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_source_packet_lost (stop)</CODE><BR>
<P>RTCP source report data
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_source_jitter (stop)</CODE><BR>
<P>RTCP source report data
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_source_sdes_XXX (stop)</CODE><BR>
<P>RTCP source report data (for each source description (sdes))
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_destination_packet_count (stop)</CODE><BR>
<P>RTCP destination report data
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_destination_packet_lost (stop)</CODE><BR>
<P>RTCP destination report data
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_destination_jitter (stop)</CODE><BR>
<P>RTCP destination report data
<P>
</LI>
<LI><CODE>(optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_destination_sdes_XXX (stop)</CODE><BR>
<P>RTCP destination report data (for each source description (sdes))
<P>
</LI>
</UL>
<P>
<H3>[RadAcct] Accounting-Response Radius Attributes</H3>

<P>The gatekeeper ignores all attributes present in Accounting-Response
Radius packets.
<P>
<P>
<H2><A NAME="sqlacct"></A> 9.4 Section [SQLAcct]</H2>

<P>This accounting module stores accounting information directly
to a SQL database. Many configuration settings are common with
other SQL modules.
<P>
<UL>
<LI><CODE>Driver=MySQL | PostgreSQL | Firebird | ODBC | SQLite</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>SQL database driver to use. Currently, <CODE>MySQL</CODE>, <CODE>PostgreSQL</CODE>, <CODE>Firebird</CODE>, <CODE>ODBC</CODE> and <CODE>SQLite</CODE> drivers
are implemented. GnuGk supports only version 3 of SQLite.
<P>
</LI>
<LI><CODE>Host=DNS[:PORT] | IP[:PORT]</CODE><BR>
Default: <CODE>localhost</CODE><BR>
<P>SQL server host address. Can be in the form of <CODE>DNS[:PORT]</CODE> or <CODE>IP[:PORT]</CODE>.
Examples: <CODE>sql.mycompany.com</CODE> or <CODE>sql.mycompany.com:3306</CODE> or <CODE>192.168.3.100</CODE>.
<P>
</LI>
<LI><CODE>Database=billing</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>The database name to connect to.
<P>
</LI>
<LI><CODE>Username=gnugk</CODE><BR>
<P>The username used to connect to the database.
<P>
</LI>
<LI><CODE>Password=secret</CODE><BR>
<P>The password used to connect to the database.
If the password is not specified, a database connection attempt 
without any password will be made.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in an encrypted form and should be created 
using the <CODE>addpasswd</CODE> utility.
<P>
</LI>
<LI><CODE>StartQuery=INSERT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines SQL query used to insert a new call record to the database. The query
is parametrized - that means parameter replacement is made before each query
is executed. Parameter placeholders are denoted by % character and can be one
letter (like %u) or whole strings (like %{src-info}). Specify %% to embed 
a percent character inside the query string (like <B>%%</B>).
For <CODE>SQLAcct</CODE> the following parameters are defined:
<UL>
<LI><CODE>%g</CODE> - gatekeeper name</LI>
<LI><CODE>%n</CODE> - call number (not unique after gatekeeper restart)</LI>
<LI><CODE>%d</CODE> - call duration (seconds)</LI>
<LI><CODE>%t</CODE> - total call duration (from Setup to Release Complete)</LI>
<LI><CODE>%c</CODE> - Q.931 disconnect cause (<B>hexadecimal</B> integer)</LI>
<LI><CODE>%r</CODE> - who disconnected the call (-1 - unknown, 0 - the gatekeeper, 1 - the caller, 2 - the callee)</LI>
<LI><CODE>%p</CODE> - PDD (Post Dial Delay) in seconds</LI>
<LI><CODE>%s</CODE> - unique (for this gatekeeper) call (Acct-Session-Id)</LI>
<LI><CODE>%u</CODE> - H.323 ID of the calling party</LI>
<LI><CODE>%{gkip}</CODE> - IP address of the gatekeeper</LI>
<LI><CODE>%{CallId}</CODE> - H.323 call identifier (16 hex 8-bit digits)</LI>
<LI><CODE>%{ConfId}</CODE> - H.323 conference identifier (16 hex 8-bit digits)</LI>
<LI><CODE>%{setup-time}</CODE> - timestamp string for Q.931 Setup message</LI>
<LI><CODE>%{alerting-time}</CODE> - timestamp string for Q.931 Alerting message</LI>
<LI><CODE>%{connect-time}</CODE> - timestamp string for a call connected event</LI>
<LI><CODE>%{disconnect-time}</CODE> - timestamp string for a call disconnect event</LI>
<LI><CODE>%{ring-time}</CODE> - time a remote phone was ringing for (from Alerting till Connect or Release Complete)</LI>
<LI><CODE>%{caller-ip}</CODE> - signaling IP address of the caller</LI>
<LI><CODE>%{caller-port}</CODE> - signaling port of the caller</LI>
<LI><CODE>%{callee-ip}</CODE> - signaling IP address of the called party</LI>
<LI><CODE>%{callee-port}</CODE> - signaling port of the called party</LI>
<LI><CODE>%{src-info}</CODE> - a colon separated list of source aliases</LI>
<LI><CODE>%{dest-info}</CODE> - a colon separated list of destination aliases</LI>
<LI><CODE>%{Calling-Station-Id}</CODE> - calling party number</LI>
<LI><CODE>%{Called-Station-Id}</CODE> - called party number (rewritten Dialed-Number)</LI>
<LI><CODE>%{Dialed-Number}</CODE> - dialed number (as received from the calling party)</LI>
<LI><CODE>%{caller-epid}</CODE> - endpoint identifier of the calling party</LI>
<LI><CODE>%{callee-epid}</CODE> - endpoint identifier of the called party</LI>
<LI><CODE>%{call-attempts}</CODE> - number of attempts to establish the calls (with failover this can be > 1)</LI>
<LI><CODE>%{last-cdr}</CODE> - is this the last CDR for this call ? (0 / 1) only when using failover this can be 0</LI>
<LI><CODE>%{media-oip}</CODE> - caller's RTP media IP (only for H.245 routed/tunneled calls)</LI>
<LI><CODE>%{codec}</CODE> - audio codec used during the call (only for H.245 routed/tunneled calls)</LI>
<LI><CODE>%{bandwidth}</CODE> - bandwidth for this call</LI>
<LI><CODE>%{client-auth-id}</CODE> - an ID provided to GnuGk when authenticating the call (through SqlAuth)</LI>
</UL>
<P>Sample query string:
<BLOCKQUOTE><CODE>
<PRE>
INSERT INTO call (gkname, sessid, username, calling, called) 
        VALUES ('%g', '%s', '%u', '%{Calling-Station-Id}', '%{Called-Station-Id}')
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>StartQueryAlt=INSERT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines a SQL query used to insert a new call record to the database in case
the <CODE>StartQuery</CODE> failed for some reason (the call already exists, for example).
The syntax and parameters are the same as for <CODE>StartQuery</CODE>.
<P>
</LI>
<LI><CODE>UpdateQuery=UPDATE ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines a SQL query used to update a call record in the database with the current 
call state. The syntax and parameters are the same as for <CODE>StartQuery</CODE>.
<P>Sample query string:
<BLOCKQUOTE><CODE>
<PRE>
UPDATE call SET duration = %d WHERE gkname = '%g' AND sessid = '%s'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>StopQuery=UPDATE ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines SQL query used to update a call record in the database when the call
is finished (disconnected). The syntax and parameters are the same 
as for <CODE>StartQuery</CODE>.
<P>Sample query string:
<BLOCKQUOTE><CODE>
<PRE>
UPDATE call SET duration = %d, dtime = '%{disconnect-time}' WHERE gkname = '%g' AND sessid = '%s'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>StopQueryAlt=INSERT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines a SQL query used to update call record in the database when the call
is finished (disconnected) in case the regular <CODE>StopQuery</CODE> failed (because
the call record does not yet exist, for example). The syntax and parameters 
are the same as for <CODE>StartQuery</CODE>.
<P>Sample query string:
<BLOCKQUOTE><CODE>
<PRE>
INSERT INTO call (gkname, sessid, username, calling, called, duration) 
        VALUES ('%g', '%s', '%u', '%{Calling-Station-Id}', '%{Called-Station-Id}', %d)
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>AlertQuery=UPDATE ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines SQL query used to update a call record in the database when the call is alerting.
<P>
</LI>
<LI><CODE>RegisterQuery=INSERT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines SQL query used to update the database when an endpoint registers.
<P>
</LI>
<LI><CODE>UnregisterQuery=DELETE ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines SQL query used to update the database when an endpoint unregisters.
<P>
</LI>
<LI><CODE>TimestampFormat=MySQL</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Format of timestamp strings used in queries. If this setting
is not specified, the global one from the main gatekeeper section is used.
<P>
</LI>
<LI><CODE>MinPoolSize=5</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Number of concurrent SQL connections in the pool. The first available connection
in the pool is used to store accounting data.
<P>
</LI>
</UL>
<P>
<H3><A NAME="mysqlscheme"></A> A Sample MySQL Schema</H3>

<P>The SQLAcct module is designed to adapt to whatever database structure you already have. You can define all queries so they fit your existing tables.
Here is an example of what those tables might look like in MySQL and which you can use as a starting point.
<P>Create a new database; here we use the name 'GNUGK':
<P>
<BLOCKQUOTE><CODE>
<PRE>
create database GNUGK;
</PRE>
</CODE></BLOCKQUOTE>
<P>Then create a table in this database to store you accounting data; we call the table 'CDR'.
<P>
<BLOCKQUOTE><CODE>
<PRE>
create table GNUGK.CDR (
        gatekeeper_name varchar(255),
        call_number int zerofill,
        call_duration mediumint unsigned zerofill,
                index duration_idx (call_duration),
        disconnect_cause smallint unsigned zerofill,
                index dcc_idx (disconnect_cause),
        acct_session_id varchar(255),
        h323_id varchar(255),
        gkip varchar(15),
        CallId varchar(255),
        ConfID varchar(255),
        setup_time datetime,
        connect_time datetime,
        disconnect_time datetime,
        caller_ip varchar(15),
                index srcip_idx (caller_ip),
        caller_port smallint unsigned zerofill,
        callee_ip varchar(15),
                index destip_idx (callee_ip),
        callee_port smallint unsigned zerofill,
        src_info varchar(255),
        dest_info varchar(255),
        Calling_Station_Id varchar(255),
        Called_Station_Id varchar(255),
                index dialednumber_idx (Called_Station_Id (20)),
        Dialed_Number varchar(255)
);
</PRE>
</CODE></BLOCKQUOTE>
<P>Then you need to create a username for accessing the data.
<P>
<BLOCKQUOTE><CODE>
<PRE>
mysql> GRANT delete,insert,select,update ON GNUGK.* TO 'YourDesiredUsername'@'localhost' IDENTIFIED BY 'APassword';
mysql> flush privileges;
</PRE>
</CODE></BLOCKQUOTE>
<P>With this command you will permit access to the data only from the local server. If you need to access the data from any other computer then you have to set the proper security options.
<P>For example, to permit access from the 192.168.1.0/24 network:
<P>
<BLOCKQUOTE><CODE>
<PRE>
mysql> GRANT delete,insert,select,update ON GNUGK.* TO 'YourDesiredUsername'@'192.168.1.%' IDENTIFIED BY 'APassword';
mysql> flush privileges;
</PRE>
</CODE></BLOCKQUOTE>
<P>Then you can add the following settings into your gnugk.ini file to insert and update the history of the calls into your database. 
<P>
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Acct]
SQLAcct=optional;start,stop,update
FileAcct=sufficient;stop

[FileAcct]
DetailFile=Add your desire path here something like /var/log/cdr.log
StandardCDRFormat=0
CDRString=%g|%n|%d|%c|%s|%u|%{gkip}|%{CallId}|%{ConfId}|%{setup-time}|%{connect-time}|%{disconnect-time}|%{caller-ip}|%{caller-port}|%{callee-ip}|%{callee-port}|%{src-info}|%{dest-info}|%{Calling-Station-Id}|%{Called-Station-Id}|%{Dialed-Number}
Rotate=daily
RotateTime=23:59

[SQLAcct]
Driver=MySQL
Database=GNUGK
Username=YourDesiredUsername
Password=APassword
StartQuery= insert into CDR (gatekeeper_name, call_number, call_duration, disconnect_cause, acct_session_id, h323_id, gkip, CallId, ConfId, setup_time, connect_time, disconnect_time, caller_ip, caller_port, callee_ip, callee_port, src_info, dest_info, Calling_Station_Id, Called_Station_Id, Dialed_Number) values ('%g', '%n', %d, %c, '%s', '%u', '%{gkip}', '%{CallId}', '%{ConfId}', '%{setup-time}', '%{connect-time}', '%{disconnect-time}', '%{caller-ip}', '%{caller-port}', '%{callee-ip}', '%{callee-port}', '%{src-info}', '%{dest-info}', '%{Calling-Station-Id}', '%{Called-Station-Id}', '%{Dialed-Number}')

StartQueryAlt= insert into CDR (gatekeeper_name, call_number, call_duration, disconnect_cause, acct_session_id, h323_id, gkip, CallId, ConfID, setup_time, connect_time, disconnect_time, caller_ip, caller_port, callee_ip, callee_port, src_info, dest_info, Calling_Station_Id, Called_Station_Id, Dialed_Number) values ('%g', '%n', %d, %c, '%s', '%u', '%{gkip}', '%{CallId}', '%{ConfID}', '%{setup-time}', '%{connect-time}', '%{disconnect-time}', '%{caller-ip}', '%{caller-port}', '%{callee-ip}', '%{callee-port}', '%{src-info}', '%{dest-info}', '%{Calling-Station-Id}', '%{Called-Station-Id}', '%{Dialed-Number}')

UpdateQuery= update CDR set call_duration=%d where gatekeeper_name='%g' and acct_session_id='%s'

StopQuery= update CDR set call_duration=%d, disconnect_cause=%c, disconnect_time='%{disconnect-time}' where gatekeeper_name='%g' and acct_session_id='%s'

StopQueryAlt= insert into CDR (gatekeeper_name, call_number, call_duration, disconnect_cause, acct_session_id, h323_id, gkip, CallId, ConfID, setup_time, connect_time, disconnect_time, caller_ip, caller_port, callee_ip, callee_port, src_info, dest_info, Calling_Station_Id, Called_Station_Id, Dialed_Number) values ('%g STOP Alt', '%n', %d, %c, '%s', '%u', '%{gkip}', '%{CallId}', '%{ConfID}', '%{setup-time}', '%{connect-time}', '%{disconnect-time}', '%{caller-ip}', '%{caller-port}', '%{callee-ip}', '%{callee-port}', '%{src-info}', '%{dest-info}', '%{Calling-Station-Id}', '%{Called-Station-Id}', '%{Dialed-Number}')

TimestampFormat=MySQL
</PRE>
</CODE></BLOCKQUOTE>
<P>
<P>
<H2><A NAME="statusacct"></A> 9.5 Section [StatusAcct]</H2>

<P>This accounting module sends all accounting information to the
status port where it can be used to interface to
external systems in real time.
<P>
<UL>
<LI><CODE>StartEvent=CALL|Start|%{CallId}</CODE><BR>
Default: <CODE>CALL|Start|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}</CODE><BR>
<P>Defines the event to display for a new call. The string is parametrized
with the same variables as the other accounting modules (See 
<A HREF="#sqlacct">[SQLAcct]</A>).
<P>
</LI>
<LI><CODE>StopEvent=CALL|Stop|%{CallId}</CODE><BR>
Default: <CODE>CALL|Stop|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}</CODE><BR>
<P>Defines the event when a call is finished (disconnected). The syntax and parameters are the same as for <CODE>StartEvent</CODE>. This event is equivalent to the old status port CDR event, but more flexible.
<P>
</LI>
<LI><CODE>UpdateEvent=CALL|Update|%{CallId}</CODE><BR>
Default: <CODE>CALL|Update|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}</CODE><BR>
<P>Defines event used to update the current call state. The syntax and parameters are the same as for <CODE>StartEvent</CODE>.
<P>
</LI>
<LI><CODE>AlertEvent=CALL|Alert|%{CallId}</CODE><BR>
Default: <CODE>CALL|Alert|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}</CODE><BR>
<P>Defines the event when a call is alerting. The syntax and parameters are the same as for <CODE>StartEvent</CODE>.
<P>
</LI>
<LI><CODE>ConnectEvent=CALL|Connect|%{CallId}</CODE><BR>
Default: <CODE>CALL|Connect|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}</CODE><BR>
<P>Defines the event when a call is connected. The syntax and parameters are the same as for <CODE>StartEvent</CODE>.
<P>
</LI>
<LI><CODE>RegisterEvent=CALL|Register|%{endpoint-ip}</CODE><BR>
Default: <CODE>CALL|Register|%{endpoint-ip}:%{endpoint-port}|%{aliases}</CODE><BR>
<P>Defines the event when an endpoint registers. The syntax and parameters are the same as for <CODE>StartEvent</CODE>.
<P>
</LI>
<LI><CODE>UnregisterEvent=CALL|Unregister|%{endpoint-ip}</CODE><BR>
Default: <CODE>CALL|Unregister|%{endpoint-ip}:%{endpoint-port}|%{aliases}</CODE><BR>
<P>Defines the event when an endpoint registers. The syntax and parameters are the same as for <CODE>StartEvent</CODE>.
<P>
</LI>
<LI><CODE>TimestampFormat=MySQL</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Format of timestamp strings used in events. If this setting
is not specified, the global one from the main gatekeeper section is used.
<P>
</LI>
</UL>
<P>In addition to the CDR parameters, Register and Unregister events can use the following parameters:
<UL>
<LI><CODE>%{endpoint-ip}</CODE> - IP number of the endpoint</LI>
<LI><CODE>%{endpoint-port}</CODE> - port number of the endpoint</LI>
<LI><CODE>%{epid}</CODE> - the endpoint ID</LI>
<LI><CODE>%{aliases}</CODE> - the comma deparated list of aliases the endpoint has registered with</LI>
</UL>
<P>
<P>
<H2><A NAME="syslogacct"></A> 9.6 Section [SyslogAcct]</H2>

<P>This accounting module sends accounting information to the
Unix syslog and is not available on Windows. The local syslog daemon will then route the messages according to its configuration, generally specified in /etc/syslog.conf.
<P>
<UL>
<LI><CODE>SyslogFacility=LOG_LOCAL1</CODE><BR>
Default: <CODE>LOG_USER</CODE><BR>
<P>Set the syslog facility to one of LOG_USER, LOG_DAEMON, LOG_AUTH, LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7.
<P>
</LI>
<LI><CODE>SyslogLevel=LOG_NOTICE</CODE><BR>
Default: <CODE>LOG_INFO</CODE><BR>
<P>Set the syslog level to LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO or LOG_DEBUG.
<P>
</LI>
<LI><CODE>StartEvent=CALL|Start|%{CallId}</CODE><BR>
Default: <CODE>CALL|Start|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}</CODE><BR>
<P>Defines the event to display for a new call. The string is parametrized
with the same variables as the other accounting modules (See 
<A HREF="#sqlacct">[SQLAacct]</A>).
<P>
</LI>
<LI><CODE>StopEvent=CALL|Stop|%{CallId}</CODE><BR>
Default: <CODE>CALL|Stop|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}</CODE><BR>
<P>Defines the event when a call is finished (disconnected). The syntax and parameters are the same as for <CODE>StartEvent</CODE>. This event is equivalent to the old status port CDR event, but more flexible.
<P>
</LI>
<LI><CODE>UpdateEvent=CALL|Update|%{CallId}</CODE><BR>
Default: <CODE>CALL|Update|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}</CODE><BR>
<P>Defines event used to update the current call state. The syntax and parameters are the same as for <CODE>StartEvent</CODE>.
<P>
</LI>
<LI><CODE>ConnectEvent=CALL|Connect|%{CallId}</CODE><BR>
Default: <CODE>CALL|Connect|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}</CODE><BR>
<P>Defines the event when a call is connected. The syntax and parameters are the same as for <CODE>StartEvent</CODE>.
<P>
</LI>
<LI><CODE>TimestampFormat=MySQL</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Format of timestamp strings used in events. If this setting
is not specified, the global one from the main gatekeeper section is used.
<P>
</LI>
</UL>

<H2><A NAME="s10">10. Neighbor Configuration</A></H2>

<P>
<H2><A NAME="neighbor"></A> 10.1 Section [RasSrv::Neighbors]</H2>

<P>If the destination of an ARQ is unknown, the gatekeeper sends LRQs to
its neighbors to ask if they have the destination endpoint.
A neighbor is selected if one of its prefixes matches the destination
or it has the ``<CODE>*</CODE>'' prefix. More than one prefix may be specified.
You can use special characters ``<CODE>.</CODE>''  to do wildcard
matching and ``<CODE>!</CODE>'' to disable a specific prefix.
<P>Conversely, the gatekeeper will only reply to LRQs sent from neighbors
defined in this section.
If you specify an empty prefix, no LRQ will be sent to that neighbor,
but the gatekeeper will accept LRQs from it. The empty prefix is denoted
by a single semicolon appended to the neighbor entry. Example:<BR><BR>
<CODE>  GK1=192.168.0.5;</CODE><BR><BR>
If you skip the semicolon, LRQs will be always sent to this neighbor.
<P>The <CODE>password</CODE> field is used to authenticate LRQs from that neighbor.
See section 
<A HREF="#gkauth">[Gatekeeper::Auth]</A> for details.
<P>Whether a call is accepted from a neighbor also depends on the AcceptNeighborsCalls switch in the 
<A HREF="#routed">[RoutedMode]</A> section.
<P>The gatekeeper types have the following characteristics:
<UL>
<LI><CODE>GnuGk</CODE><BR>
When in doubt, use the 
<A HREF="http://www.gnugk.org/">GnuGk gatekeeper</A> type. This also activates H.460.23 / H.460.24.
</LI>
<LI><CODE>CiscoGk</CODE><BR>
GnuGk will pretend to be a Cisco gatekeeper and send fake manufacturer data.
</LI>
<LI><CODE>ClarentGk</CODE><BR>
Clarent gatekeeper can't decode nonStandardData in LRQs, so GnuGk will filter it out.
</LI>
<LI><CODE>GlonetGk</CODE><BR>
Limited support for LRQ forwarding.</LI>
</UL>
<P>
<DL>
<P><CODE>GKID="GnuGk" | "CiscoGk" | "ClarentGk" | "GlonetGk"</CODE>
<P>
<DT><B>Example:</B><DD><P><CODE>[RasSrv::Neighbors]</CODE><BR>
<CODE>GK1=CiscoGk</CODE><BR>
<CODE>GK2=GnuGk</CODE><BR><BR>
<CODE>[Neighbor::GK1]</CODE><BR>
<CODE>GatekeeperIdentifier=GK1</CODE><BR>
<CODE>Host=192.168.1.1</CODE><BR>
<CODE>SendPrefixes=02</CODE><BR>
<CODE>AcceptPrefixes=*</CODE><BR>
<CODE>ForwardLRQ=always</CODE><BR><BR>
<CODE>[Neighbor::GK2]</CODE><BR>
<CODE>GatekeeperIdentifier=GK2</CODE><BR>
<CODE>Host=192.168.1.2</CODE><BR>
<CODE>SendPrefixes=03,0048</CODE><BR>
<CODE>AcceptPrefixes=0049,001</CODE><BR>
<CODE>ForwardHopCount=2</CODE><BR>
<CODE>ForwardLRQ=depends</CODE><BR><BR>
</DL>
<P>The <CODE>[RasSrv::Neighbors]</CODE> section is only used to specify the gatekeeper type. The configuration for each neighbor is placed in a separate section.
<P>
<H2><A NAME="lrqfeatures"></A> 10.2 Section [RasSrv::LRQFeatures]</H2>

<P>Defines some features of LRQ and LCF.
<UL>
<LI><CODE>NeighborTimeout=1</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>Timeout value in seconds to wait for responses from neighbors.
If no neighbor responds before the timeout, the gatekeeper will
reply with an ARJ to the endpoint sending the ARQ.
<P>
<P>
</LI>
<LI><CODE>SendRetries=4</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>Number of tries to send LRQ to neighbors.
If there is no response from neighbors after retries timeout, the gatekeeper will
reply with a LRJ to the endpoint sending the LRQ.
<P>
</LI>
<LI><CODE>ForwardHopCount=2</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If the gatekeeper receives a LRQ that the destination is unknown
it may forward this message to its neighbors.
<P>When the gatekeeper receives a LRQ and decides that the message
should be forwarded on to another gatekeeper, it first decrements
<B>hopCount</B> field of the LRQ.
If <B>hopCount</B> has reached 0, the gatekeeper shall not forward the message.
This option defines the number of gatekeepers through which a LRQ
may propagate. Note that it only affects the sender of LRQ, not the forwarder.
This setting can be overridden via the configuration section for a particular neighbor.
<P>
</LI>
<LI><CODE>AcceptForwardedLRQ=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Whether to accept an LRQ forwarded from neighbors.
This setting can be overridden with configuration
of a particular neighbor.
<P>
</LI>
<LI><CODE>ForwardResponse=0</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>If the gatekeeper forwards a received LRQ message it can decide either
to receive the LCF response or to let it travel back directly to the LRQ
originator. Set this option to 1 if the gatekeeper needs to receive LCF
messages for forwarded LRQs. This setting can be overridden with configuration
of a particular neighbor.
<P>
</LI>
<LI><CODE>ForwardLRQ=always | never | depends</CODE><BR>
Default: <CODE>depends</CODE><BR>
<P>This settings determines whether the received LRQ should be forwarded
or not. <CODE>always</CODE> forwards LRQ unconditionally, <CODE>never</CODE> blocks LRQ
forwarding, <CODE>depends</CODE> tells the gatekeeper to forward LRQ only if its
hop count is greater than 1. This setting can be overridden with configuration
of a particular neighbor.
<P>
</LI>
<LI><CODE>AcceptNonNeighborLRQ=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Whether to accept a LRQ forwarded from parties not defined as Neighbors.
This can be used with SRV routing policy to place calls to third party gatekeepers.
This should be used in conjunction with a LRQ Authentication policy.
<P>
</LI>
<LI><CODE>AcceptNonNeighborLCF=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>This setting disables matching of the LRQ responder's IP address and
specified neighbor IP addresses in order to accept LCF message responses
from any IP address. This has primary importance when a
multiple level gatekeeper hierarchy is used without routed Q.931 signaling.
As a minimal security, only LRQ/LCF sequence numbers will be checked accordingly. This feature is required by the
national gatekeepers connected to the Global Dialing Scheme (GDS), see
<A HREF="http://www.vide.net/help/gdsintro.shtml">http://www.vide.net/help/gdsintro.shtml</A>
for more information.
WARNING: Enabling receiving LCF from other than the LRQ destination IP is a significant security risk. 
Use this setting with extreme caution.
</LI>
</UL>
<P>
<P>
<P>
<H2>10.3 Section [Neighbor::...]</H2>

<P>Sections starting with <CODE>[Neighbor::</CODE> are specific for one neighbor.  If
you define a [Neighbor::...] section, the default values of all
settings in 
<A HREF="#lrqfeatures">[RasSrv::LRQFeatures]</A> will be applied to
this neighbor.  You may override the global defaults through configuration options in
each neighbor-specific section.
<P>
<UL>
<LI><CODE>GatekeeperIdentifier=GKID</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Gatekeeper identifier for this neighbor. If this option is not specified,
the identifier is taken from the second part of the <CODE>Neighbor::</CODE> section name.
<P>
</LI>
<LI><CODE>Host=192.168.1.1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>An IP address for this neighbor.
<P>
</LI>
<LI><CODE>Password=secret</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>A password to be used to validate crypto tokens received from incoming LRQs.
<CODE>Not yet implemented, yet.</CODE>
<P>
</LI>
<LI><CODE>Dynamic=0</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>1 means that the IP address for this neighbor can change.
<P>
</LI>
<LI><CODE>SendPrefixes=004,002:=1,001:=2</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>A list of prefixes that this neighbor expects to receive LRQs for.
If '*' is specified, LRQs will always be sent to this neighbor.
A priority can be given to each prefix for each neighbor (using := syntax),
so in case of multiple LCF received from multiple neighbor, the one
with the highest priority will be selected to route the call.
One can also direct the gatekeeper to send LRQ to this neighbor
based on an alias type:<BR>
SendPrefixes=h323_ID,dialedDigits,001<BR>
<P>
</LI>
<LI><CODE>SendAliases=4526354,2000-2010,frank</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>A list of specific aliases this neighbor expects to receive LRQs for.
For E.164 numbers, ranges can be specified.
<P>
</LI>
<LI><CODE>AcceptPrefixes=*</CODE><BR>
Default: <CODE>*</CODE><BR>
<P>A list of prefixes that GnuGk will accept in LRQs received
from this neighbor. If '*' is specified, all LRQs will be accepted from this neighbor.
One can also direct the gatekeeper to accept LRQ from this neighbor
based on an alias type:<BR>
AcceptPrefixes=dialedDigits<BR>
<P>
</LI>
<LI><CODE>ForwardHopCount=2</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>If the gatekeeper receives an LRQ that the destination is either unknown,
it may forward this message to its neighbors.
When the gatekeeper receives an LRQ and decides that the message
should be forwarded on to another gatekeeper, it first decrements
<B>hopCount</B> field of the LRQ.
If <B>hopCount</B> has reached 0, the gatekeeper shall not forward the message.
This options defines the number of gatekeepers through which an LRQ
may propagate. Note it only affects the sender of LRQ, not the forwarder.
<P>
</LI>
<LI><CODE>AcceptForwardedLRQ=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Whether to accept an LRQ forwarded from this neighbor.
<P>
</LI>
<LI><CODE>ForwardResponse=0</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>If the gatekeeper forwards received LRQ message it can decide either
to receive the LCF response or to let it travel back directly to the LRQ
originator. Set this option to "1" if the gatekeeper needs to receive LCF
messages for forwarded LRQs.
<P>
</LI>
<LI><CODE>ForwardLRQ=always | never | depends</CODE><BR>
Default: <CODE>depends</CODE><BR>
<P>This settings determines whether the received LRQ should be forwarded
or not. <CODE>always</CODE> forwards LRQ unconditionally, <CODE>never</CODE> blocks LRQ
forwarding, <CODE>depends</CODE> tells the gatekeeper to forward LRQ only if its
hop count is greater than 1.
<P>
</LI>
<LI><CODE>UseH46018=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Enable H.460.18 keep-alive messages to this neighbor. Set this switch only on the H.460.18
client side that is supposed to send the keep-alive ServiceControlIndication (SCI) messages.
<P>
</LI>
<LI><CODE>SendPassword=secret</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>
<P>
<P>EXPERIMENTAL: The password to send to the neighbor (right now only used for H.460.18 SCI).
<P>
</LI>
</UL>
<P>
<H2><A NAME="epconfig"></A> <A NAME="s11">11. Per-Endpoint Configuration</A></H2>

<P>In addition to the standard configuration file options, per-endpoint configuration
settings can be specified in the 
<A HREF="http://www.gnugk.org/">GnuGk</A> config file.
The syntax is as follows:
<P>
<H2>11.1 Section [EP::...]</H2>

<P>
<BLOCKQUOTE><CODE>
<PRE>
[EP::ALIAS]
Key Name=Value String
</PRE>
</CODE></BLOCKQUOTE>
<P><CODE>ALIAS</CODE> should be replaced with the actual alias for the endpoint the settings
should apply to. Currently, the following options are recognized:
<P>
<UL>
<LI><CODE>Capacity=10</CODE><BR>
Default: <CODE>-1</CODE><BR>
<P>Call capacity for an endpoint. No more than <CODE>Capacity</CODE> concurrent
calls will be sent to this endpoint. In case of gateways, if more than one
gateway matches a dialed number, a call will be sent to the first available
gateway which has available capacity.
<P>
</LI>
<LI><CODE>PrefixCapacities=^0049:=10,^(0044|0045):=20</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Limit the capacity for certain prefixes. Regular expressions can be used to specify
the prefix and specify a combined capacity for a group of prefixes. For a gateway to
be considered available a.) the prefix must have capacity left and b.) the total gateway
capacity (see above) must not be exceeded.
<P>
</LI>
<LI><CODE>GatewayPriority=1</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Applicable only to gateways. Allows priority based routing when more
than one gateway matches a dialed number. Lower values indicate a higher gateway priority.
A call is routed to the first available gateway
(that has available capacity) with the highest priority (the lowest
<CODE>GatewayPriority</CODE> values). In case the gateway priority contradicts prefix priority (see section 
<A HREF="#gwprefixes">[RasSrv::GWPrefixes]</A>)  
for details), prefix priority will take precedence.
<P>
</LI>
<LI><CODE>GatewayPrefixes=0048,0049:=2,0044</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Additional prefixes for this gateway. Applies only to gateways.  Special
characters <CODE>.</CODE> and <CODE>!</CODE> can be used to match any digit or to disable
the prefix.  You may use the := syntax to set a prefix priority in the same
manner as in 
<A HREF="#gwprefixes">[RasSrv::GWPrefixes]</A> section.  If
no priority is explicitly configured for a prefix, then the gateway priority
is used.
<P>
</LI>
<LI><CODE>AddNumbers=4212,5650-5630,6000</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Add E.164 numbers to this endpoint. The new aliases can either be specified
as a list of numbers or as number ranges.
<P>
</LI>
<LI><CODE>CalledTypeOfNumber=1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets Called-Party-Number type of number to the specified value
for calls sent to this endpoint
(0 - UnknownType, 1 - InternationalType, 2 - NationalType,
3 - NetworkSpecificType, 4 - SubscriberType, 6 - AbbreviatedType, 7 - ReservedType).
<P>
</LI>
<LI><CODE>CallingTypeOfNumber=1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets Calling-Party-Number type of number to the specified value
for calls sent to this endpoint
(0 - UnknownType, 1 - InternationalType, 2 - NationalType,
3 - NetworkSpecificType, 4 - SubscriberType, 6 - AbbreviatedType, 7 - ReservedType).
<P>
</LI>
<LI><CODE>CalledPlanOfNumber=1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets Called-Numbering-Plan of number to the specified value
for calls sent to this endpoint
(0 - UnknownType, 1 - ISDN, 3 - X.121 numbering, 4 - Telex, 8 - National standard, 9 - private numbering).
<P>
</LI>
<LI><CODE>CallingPlanOfNumber=1</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Sets Calling-Numbering-Plan of number to the specified value
for calls sent to this endpoint
(0 - UnknownType, 1 - ISDN, 3 - X.121 numbering, 4 - Telex, 8 - National standard, 9 - private numbering).
<P>
</LI>
<LI><CODE>Proxy=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Enables/disables proxying calls sent to this endpoint (0 - do not
change global proxy settings, 1 - force proxy mode, 2 - disable proxy mode).
<P>
</LI>
<LI><CODE>TranslateReceivedQ931Cause=17:=34</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Translate received cause codes in ReleaseComplete messages from this endpoint.
In the above example code 17 (User busy) will be translated into cause code 34 (No circuit/channel available).
<P>
</LI>
<LI><CODE>TranslateSentQ931Cause=21:=34,27:=34</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Translate cause codes in ReleaseComplete messages sent out to this endpoint.
In the above example code 21 and 27 will be translated into cause code 34, because this particular gateway might deal with error code 34 better than with others.
<P>
</LI>
<LI><CODE>DisableH46018=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Disable H.460.18/.19 for this endpoint.
<P>
</LI>
</UL>
<P>Example:
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::PermanentEndpoints]
192.168.1.1=gw1;48
192.168.1.2=gw2;48,!4850,!4860,!4869,!4888

[EP::gw1]
Capacity=60
GatewayPriority=1

[EP::gw2]
Capacity=30
GatewayPriority=2
</PRE>
</CODE></BLOCKQUOTE>
<P>In this example, calls will be sent to the gateway <CODE>gw1</CODE> until its
capacity is fully utilized (60 concurrent calls) and then to the gateway <CODE>gw2</CODE>.
<P>
<H2><A NAME="s12">12. Advanced Configuration</A></H2>

<P>
<H2><A NAME="calltable"></A> 12.1 Section [CallTable]</H2>

<P>
<UL>
<LI><CODE>GenerateNBCDR=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Generate CDRs for calls from neighbor zones.
The IP and endpoint ID of the calling party is printed as empty.
This is usually used for debugging purposes.
<P>
</LI>
<LI><CODE>GenerateUCCDR=0</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Generate CDRs for calls that are unconnected. This is usually
used for debugging purposes. Note that a call is considered unconnected
only if the gatekeeper uses routed mode and a Q.931 "Connect" message is not
received by the gatekeeper. In direct mode, a call is always considered
connected.
<P>
</LI>
<LI><CODE>DefaultCallDurationLimit=3600</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Default maximum call duration limit (seconds).
Set it to <CODE>0</CODE> to disable this feature and not limit
call duration.
<P>
</LI>
<LI><CODE>AcctUpdateInterval=60</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>A time interval (seconds) for accounting updates to be logged
for each call in progress. The exact details of the accounting updates
depend on accounting logger modules selected (see section
<A HREF="#gkacct">[Gatekeeper::Acct]</A>). In general, the accounting
update is to provide back-end services with incrementing call duration
for connected calls.
The default value "0" disables accounting updates.
Please note that setting this to a short interval may decrease gatekeeper performance.
<P>
</LI>
<LI><CODE>TimestampFormat=Cisco</CODE><BR>
Default: <CODE>RFC822</CODE><BR>
<P>Format of timestamp strings printed inside CDRs. You can use the same list of formats as specified in the 
<A HREF="#gkmain">[Gatekeeper::Main]</A> section.
<P>
</LI>
<LI><CODE>IRRFrequency=60</CODE><BR>
Default: <CODE>120</CODE><BR>
<P>Set the irrFrequency in ACF messages. 0 turns it off.
<P>
</LI>
<LI><CODE>IRRCheck=TRUE</CODE><BR>
Default: <CODE>FALSE</CODE><BR>
<P>Check if both endpoints in a call send the requested IRRs.
A call will be terminated if one of the endpoints didn't send
an IRR after 2 * irrFrequency.
<P>
</LI>
<LI><CODE>SingleFailoverCDR=FALSE</CODE><BR>
Default: <CODE>TRUE</CODE><BR>
<P>When failover is active, more than one gateway may be tried to
establish a call. This switch defines if one or multiple CDRs
are generated for such a call.
<P>
</LI>
<LI><CODE>DisabledCodecs=g711Alaw64k;g711Ulaw64k;h263VideoCapability;</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Filter out certain codecs. Please note the trailing semicolon. Calls must be
H.245 routed or proxied for codec filtering to work.
This setting can be overridden on a per-call basis by using the Radius attribute 'disable-codec'.
<P>
</LI>
</UL>
<P>
<H2><A NAME="h225toq931"></A> 12.2 Section [H225toQ931]</H2>

<P>When converting between H.225 reasons and Q.931 cause codes, GnuGk
uses a conversion table. Using this section you can change this mapping.
<P>
<BLOCKQUOTE>
<CODE>[H225toQ931]<BR>
;0=34 # noBandwidth<BR>
;1=47 # gatekeeperResources<BR>
2=34 # unreachableDestination => NoCircuitChannelAvailable (default 3)<BR>
;3=16 # destinationRejection<BR>
;4=88 # invalidRevision<BR>
;5=111 # noPermission<BR>
;6=38 # unreachableGatekeeper<BR>
;7=42 # gatewayResources<BR>
;8=28 # badFormatAddress<BR>
;9=41 # adaptiveBusy<BR>
;10=17 # inConf<BR>
;11=31 # undefinedReason<BR>
;12=16 # facilityCallDeflection<BR>
;13=31 # securityDenied<BR>
14=34 # calledPartyNotRegistered => NoCircuitChannelAvailable (default 20)<BR>
;15=31 # callerNotRegistered<BR>
;16=47 # newConnectionNeeded<BR>
;17=127 # nonStandardReason<BR>
;18=31 # replaceWithConferenceInvite<BR>
;19=31 # genericDataReason<BR>
;20=31 # neededFeatureNotSupported<BR>
;21=127 # tunnelledSignallingRejected<BR></CODE>
</BLOCKQUOTE>
<P>
<H2><A NAME="gkqosmonitor"></A> 12.3 Section [GkQoSMonitor]</H2>

<P>Use H.460.9 to collect quality of service information from endpoints. 
Endpoints must support H.460.9 for this service to function.
<P>
<UL>
<LI><CODE>Enable=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Defines whether to enable or disable the feature. If enabled, this function
with respond to supportedFeature requests from clients so clients know to
send QoS statistics to the gatekeeper.
<P>
</LI>
<LI><CODE>CallEndOnly=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Define whether to collect the information via IRR messages or to only collect 
QoS information at the end of a call. 
<P>
</LI>
<LI><CODE>DefaultFile=qos.txt</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define the output file for QoS logs. If a file is not defined the
QoS information is output as an item in the Trace File at trace level 4
</LI>
</UL>
<P>
<H2>12.4 Section [GkQoSMonitor::SQL]</H2>

<P>This section allows you to store QoS information in a database.
You can use the same database parameters as defined in 
<A HREF="#sqlpasswordauth">[SQLPasswordAuth]</A>.
<P>
<UL>
<LI><CODE>Query=INSERT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines the SQL query used to store the QoS information.
<P>The following parameters are defined:
<UL>
<LI><CODE>%g</CODE> - gatekeeper ID</LI>
<LI><CODE>%{ConfId}</CODE> - conference ID</LI>
<LI><CODE>%{session}</CODE> - session</LI>
<LI><CODE>%{caller-ip}</CODE> - caller IP</LI>
<LI><CODE>%{caller-port}</CODE> - caller port</LI>
<LI><CODE>%{caller-nat}</CODE> - is caller NATted (0 or 1)</LI>
<LI><CODE>%{callee-ip}</CODE> - caller IP</LI>
<LI><CODE>%{callee-port}</CODE> - caller port</LI>
<LI><CODE>%{avgdelay}</CODE> - average delay</LI>
<LI><CODE>%{packetloss}</CODE> - packet loss</LI>
<LI><CODE>%{packetloss-percent}</CODE> - packet loss percentage</LI>
<LI><CODE>%{avgjitter}</CODE> - average jitter</LI>
<LI><CODE>%{bandwidth}</CODE> - bandwidth</LI>
<LI><CODE>%t</CODE> - timestamp
</LI>
</UL>
<P>Sample query string:
<BLOCKQUOTE><CODE>
<PRE>
INSERT INTO qos SET caller_ip="%{caller-ip}", bandwidth="%{bandwidth}, timestamp=%t
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
</UL>
<P>
<H2><A NAME="endpoint"></A> 12.5 Section [Endpoint]</H2>

<P>The gatekeeper can function as an endpoint by registering with another gatekeeper, allowing
you to build gatekeeper hierarchies.
This section defines the endpoint features for the gatekeeper.
<P>
<UL>
<LI><CODE>Gatekeeper=10.0.1.1</CODE><BR>
Default: <CODE>no</CODE><BR>
<P>Define a parent gatekeeper for 
<A HREF="http://www.gnugk.org/">GnuGk</A> to register with.
When call in the routing process reaches the 'parent' routing policy,
it will route all calls to this gatekeeper.
<P>Make sure you don't register with yourself, the results can be very confusing.
<P>
</LI>
<LI><CODE>Type=Gateway</CODE><BR>
Default: <CODE>Gateway</CODE><BR>
<P>Define the terminal type GnuGk will use when it registers.
Valid options are <CODE>Gateway</CODE> or <CODE>Terminal</CODE>.
<P>
</LI>
<LI><CODE>Vendor=Cisco | GnuGk | Generic</CODE><BR>
Default: <CODE>GnuGk</CODE><BR>
<P>Choose parent gatekeeper type to enable vendor specific
extensions.
<P>
</LI>
<LI><CODE>H323ID=ProxyGK</CODE><BR>
Default: <CODE>&lt;Name&gt;</CODE><BR>
<P>Specify the H.323 ID aliases for the endpoint.
Multiple aliases can be separated by comma.
<P>
</LI>
<LI><CODE>E164=18888600000,18888700000</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define the E.164 (dialedDigits) aliases for the endpoint.
Multiple aliases can be separated by comma.
<P>
</LI>
<LI><CODE>Password=123456</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Specify a password to be sent to the parent gatekeeper.
<P>All RAS requests will contain the password in the <B>cryptoTokens</B> field
(MD5 &amp; HMAC-SHA1-96) and the <B>tokens</B> field (CAT).
To send RAS requests without the <B>cryptoTokens</B> and <B>tokens</B> fields,
set the password to be empty.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.
<P>The password will be used in LRQs sent to neighbor gatekeepers.
<P>
</LI>
<LI><CODE>Prefix=188886,188887</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Register the specified prefixes with the parent gatekeeper.
Only takes effect when the Type is <CODE>Gateway</CODE>.
<P>
</LI>
<LI><CODE>TimeToLive=900</CODE><BR>
Default: <CODE>60</CODE><BR>
<P>Suggest a time-to-live value in seconds for the registration.
Note that the real time-to-live timer is assigned by the parent
gatekeeper in the RCF is sends to us in response to our RRQ.
<P>
</LI>
<LI><CODE>RRQRetryInterval=10</CODE><BR>
Default: <CODE>3</CODE><BR>
<P>Define a retry interval in seconds for resending an RRQ if no response 
is received from the parent gatekeeper. This interval is doubled with each
failure, up to a maximum RRQRetryInterval * 128 timeout.
<P>
</LI>
<LI><CODE>ARQTimeout=2</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>Define the timeout value in seconds for ARQs.
<P>
</LI>
<LI><CODE>UnregisterOnReload=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Defines whether the child gatekeeper unregisters and re-registers with
its parent after receiving a Reload command from the status port.
<P>
</LI>
<LI><CODE>NATRetryInterval=60</CODE><BR>
Default: <CODE>60</CODE><BR>
<P>How long to wait before trying to reconnect TCP NAT signaling socket (seconds).
This can happen when either the connection cannot be established or it has
been broken.
<P>
</LI>
<LI><CODE>NATKeepaliveInterval=86400</CODE><BR>
Default: <CODE>86400</CODE><BR>
<P>Define how often the TCP NAT signaling connection with a parent gatekeeper
is refreshed. As NAT boxes usually keep TCP mappings for a certain duration,
it's strongly suggested to set this to a value slightly shorter than the NAT box mapping timeout.
Refreshing is done by sending a special Q.931 IncomingCallProceeding message.
If your NAT performs TCP port translation, you may need to set it to a value
as short as 60 seconds.
<P>
</LI>
<LI><CODE>Discovery=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Configures GnuGk to attempt to discover the parent gatekeeper by first sending a GRQ.
<P>
</LI>
<LI><CODE>UseAlternateGK=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>
<P>Enable alternate gatekeepers feature. If GRJ/GCF/RCF messages received 
from a parent gatekeeper contain a list of alternate gatekeepers, this
information is stored and can be used to re-register with another gatekeeper
in case of failure. If you don't want to use this feature, set this
variable to <CODE>0</CODE>.
<P>
</LI>
<LI><CODE>GatekeeperIdentifier=ParentGK</CODE><BR>
Default: <CODE>Not set</CODE><BR>
<P>Define this parameter if you only want to accept parent gatekeepers that match
this gatekeeper identifier. Useful with GRQ discovery and can prevent 
an accidental gatekeeper match. Do not set this variable if you do not
care about gatekeeper identifiers or you use alternate gatekeepers that
can have different gatekeeper identifiers.
<P>
</LI>
<LI><CODE>EndpointIdentifier=ChildGK</CODE><BR>
Default: <CODE>Not set</CODE><BR>
<P>Set this if you want to use a specific endpoint identifier for this child
gatekeeper. If this option is not set (default), the identifier is assigned
by a parent gatekeeper in a GCF/RCF message.
<P>
</LI>
<LI><CODE>ForwardDestIp=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Forward the destCallSignalAddress in ARQs to the parent gatekeeper.
<P>
</LI>
<LI><CODE>DisableH.460.23=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>By default H.460.23 is disabled when acting as an endpoint; set this switch to turn it on.
<P>
</LI>
</UL>
<P>
<H2>12.6 Section [CTI::Agents]</H2>

<P>This section allows the configuration of a so called virtual queue to
allow inbound call distribution by an external application via the
status port.
A virtual queue has an H.323 alias that can be called like an endpoint
or it can answer to a set of aliases.
<P>Once a call arrives on the virtual queue, the gatekeeper signals
a RouteRequest on the status port and waits for an external application
to respond with either a RouteReject (which will cause the call to be rejected)
or with RouteToAlias/RouteToGateway which leads to the destination being rewritten so the call
will be routed to the alias (eg. call center agent) specified by
the external application.
<P>If no answer is received after a timeout period, the call is terminated.
<P>You can specify virtual queues in three ways:
<UL>
<LI><CODE>exact alias name</CODE> - a list of aliases is given. If a request destination
alias matches one these names, the virtual queue is activated.</LI>
<LI><CODE>prefix</CODE> - a list of prefixes is given. If a request destination alias
starts with one these prefixes, the virtual queue is activated.</LI>
<LI><CODE>regular expression</CODE> - a regular expression is given. If a request destination
alias matches the expression, the virtual queue is activated.</LI>
</UL>
<P>See the monitoring section for details on the messages and responses.
<P>
<UL>
<LI><CODE>VirtualQueueAliases</CODE><BR>
Default: <CODE>none</CODE><BR>
<P>This defines a list of H.323 aliases for the virtual queues (used with the vqueue RoutingPolicy).
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE>
<CODE>VirtualQueueAliases=sales,support</CODE>
</BLOCKQUOTE>
<BR>
</DL>
<P>
</LI>
<LI><CODE>VirtualQueuePrefixes</CODE><BR>
Default: <CODE>none</CODE><BR>
<P>This defines a list of prefixes for the virtual queues (used with the vqueue RoutingPolicy).
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE>
<CODE>VirtualQueuePrefixes=001215,1215</CODE>
</BLOCKQUOTE>
<BR>
</DL>
<P>
</LI>
<LI><CODE>VirtualQueueRegex</CODE><BR>
Default: <CODE>none</CODE><BR>
<P>This defines a regular expression for the virtual queues (used with the vqueue RoutingPolicy).
<P>
<DL>
<DT><B>Example (numbers starting with 001215 or 1215):</B><DD><P>
<BLOCKQUOTE>
<CODE>VirtualQueueRegex=^(001|1)215[0-9]*$</CODE>
</BLOCKQUOTE>
<BR>
</DL>
<P>
</LI>
<LI><CODE>RequestTimeout</CODE><BR>
Default: <CODE>10</CODE><BR>
Timeout in seconds for the external application to answer the RouteRequest.
If no answer is received during this time the call will be rejected.</LI>
</UL>
<P>
<P>
<H2><A NAME="ctimakecall"></A> 12.7 Section [CTI::MakeCall]</H2>

<P>This section contains the settings for the status port command 
<A HREF="#makecall">MakeCall</A>.
<UL>
<LI><CODE>EndpointAlias=DialOut</CODE><BR>
Default: <CODE>InternalMakeCallEP</CODE><BR>
<P>This defines the endpoint alias for the pseudo endpoint used to dial.
<P>
</LI>
<LI><CODE>UseH450=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Use a H.450.2 transfer instead of a Facility message to transfer the call from the pseudo endpoint to the actual destination.
<P>
</LI>
<LI><CODE>Gatekeeper=192.168.1.2</CODE><BR>
Default: <CODE>127.0.0.1</CODE><BR>
<P>Gatekeeper IP for the pseudo endpoint to register with.
<P>
</LI>
<LI><CODE>Interface=192.168.1.1:1730</CODE><BR>
Default: <CODE>*:1722</CODE><BR>
<P>Interface and port to use for the pseudo endpoint.
<P>
</LI>
<LI><CODE>DisableFastStart=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Disable FastStart for the pseudo endpoint.
<P>
</LI>
<LI><CODE>DisableH245Tunneling=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Disable H.245 tunneling for the pseudo endpoint.
<P>
</LI>
</UL>
<P>
<P>
<H2><A NAME="sqlconf"></A> 12.8 Section [SQLConfig]</H2>

<P>Load gatekeeper settings from a SQL database (in addition to settings
read from the config file). A generic <CODE>ConfigQuery</CODE> can be used
to read almost all setting from the database and/or one of <CODE>[RasSrv::RewriteE164]</CODE>,
<CODE>[RasSrv::PermanentEndpoints]</CODE>, <CODE>[RasSrv::Neighbors]</CODE>, 
<CODE>[RasSrv::GWPrefixes]</CODE> queries can be used to load particular settings.
Entries read from the SQL database take precedence over settings found
in the config file.
<P>
<UL>
<LI><CODE>Driver=MySQL | PostgreSQL | Firebird | ODBC | SQLite</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>SQL database driver to use. Currently, <CODE>MySQL</CODE>, <CODE>PostgreSQL</CODE>, <CODE>Firebird</CODE>, <CODE>ODBC</CODE> and <CODE>SQLite</CODE> drivers
are implemented. GnuGk supports only version 3 of SQLite.
<P>
</LI>
<LI><CODE>Host=DNS[:PORT] | IP[:PORT]</CODE><BR>
Default: <CODE>localhost</CODE><BR>
<P>SQL server host address. Can be in the form of <CODE>DNS[:PORT]</CODE> or <CODE>IP[:PORT]</CODE>.
Like <CODE>sql.mycompany.com</CODE> or <CODE>sql.mycompany.com:3306</CODE> or <CODE>192.168.3.100</CODE>.
<P>
</LI>
<LI><CODE>Database=gkconfig</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>The database name to connect to.
<P>
</LI>
<LI><CODE>Username=gnugk</CODE><BR>
<P>The username used to connect to the database.
<P>
</LI>
<LI><CODE>Password=secret</CODE><BR>
<P>The password used to connect to the database.
If the password is not specified, a database connection attempt 
without any password will be made.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.
<P>
</LI>
<LI><CODE>ConfigQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query used to read gatekeeper settings from the database. 
The query is parameterized - that means parameter replacement occurs before 
the query is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... 
strings. Specify %% to embed a percent character before a digit in a string 
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions 
like <B>%{1}123</B>. For <CODE>ConfigQuery</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>

It is expected that the query returns zero or more rows of data,
with each row consisting of <B>three</B> columns:
<UL>
<LI><CODE>column at index 0</CODE> - config section name</LI>
<LI><CODE>column at index 1</CODE> - config key (option name)</LI>
<LI><CODE>column at index 2</CODE> - config value (option value)</LI>
</UL>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
ConfigQuery=SELECT secname, seckey, secval FROM sqlconfig WHERE gk = '%1'
ConfigQuery=SELECT 'RasSrv::RRQAuth', alias, rule FROM rrqauth WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>RewriteE164Query=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query used to retrieve rewrite rules from the database
for the <CODE>[RasSrv::RewriteE164]</CODE> section. The query is parameterized 
- that means parameter replacement occurs before each query is executed. 
Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... strings. 
Specify %% to embed a percent character before a digit into string 
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions 
like <B>%{1}123</B>. For <CODE>RewriteE164Query</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>

It is expected that the query returns zero or more rows of data,
with each row consisting of two columns:
<UL>
<LI><CODE>column at index 0</CODE> - rewrite rule key</LI>
<LI><CODE>column at index 1</CODE> - rewrite rule value</LI>
</UL>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
RewriteE164Query=SELECT rkey, rvalue FROM rewriterule WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>RewriteAliasQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query used to retrieve rewrite rules from the database
for the <CODE>[RasSrv::RewriteAlias]</CODE> section. The query is parameterized 
- that means parameter replacement occurs before each query is executed. 
Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... strings. 
Specify %% to embed a percent character before a digit into string 
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions 
like <B>%{1}123</B>. For <CODE>RewriteAliasQuery</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>

It is expected that the query returns zero or more rows of data,
with each row consisting of two columns:
<UL>
<LI><CODE>column at index 0</CODE> - rewrite rule key</LI>
<LI><CODE>column at index 1</CODE> - rewrite rule value</LI>
</UL>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
RewriteAliasQuery=SELECT rkey, rvalue FROM assignedalias WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>AssignedAliasQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query used to retrieve rewrite rules from the database
for the <CODE>[RasSrv::AssignedAlias]</CODE> section. The query is parameterized 
- that means parameter replacement occurs before each query is executed. 
Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... strings. 
Specify %% to embed a percent character before a digit into string 
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions 
like <B>%{1}123</B>. For <CODE>AssignedAliasQuery</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>

It is expected that the query returns zero or more rows of data,
with each row consisting of two columns:
<UL>
<LI><CODE>column at index 0</CODE> - rewrite rule key</LI>
<LI><CODE>column at index 1</CODE> - rewrite rule value</LI>
</UL>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
AssignedAliasQuery=SELECT rkey, rvalue FROM assignedalias WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>NeighborsQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query used to retrieve neighbor entries from the database
for the <CODE>[RasSrv::Neighbors]</CODE> section. The query is parameterized 
- that means parameter replacement occurs before each query
is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... 
strings. Specify %% to embed a percent character before a digit into string 
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions 
like <B>%{1}123</B>. For <CODE>NeighborsQuery</CODE> one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>

It is expected that the query returns zero or more rows of data,
with each row consisting of six columns:
<UL>
<LI><CODE>column at index 0</CODE> - neighbor name (identifier)</LI>
<LI><CODE>column at index 1</CODE> - neighbor IP address</LI>
<LI><CODE>column at index 2</CODE> - neighbor port number</LI>
<LI><CODE>column at index 3</CODE> - optional prefixes (comma separated)</LI>
<LI><CODE>column at index 4</CODE> - optional password</LI>
<LI><CODE>column at index 5</CODE> - optional dynamic IP flag</LI>
</UL>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
NeighborsQuery=SELECT nid, nip, nport, npfx, NULL, 0 FROM neighbor WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>PermanentEndpointsQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query used to retrieve permanent endpoints from the database 
for the <CODE>[RasSrv::PermanentEndpoints]</CODE> section. The query is parameterized 
- that means parameter replacement occurs before each query
is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... 
strings. Specify %% to embed a percent character before a digit into string 
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions 
like <B>%{1}123</B>. For <CODE>PermanentEndpointsQuery</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>

It is expected that the query returns zero or more rows of data,
with each row consisting of four columns:
<UL>
<LI><CODE>column at index 0</CODE> - permanent endpoint IP address</LI>
<LI><CODE>column at index 1</CODE> - permanent endpoint port number</LI>
<LI><CODE>column at index 2</CODE> - permanent endpoint alias</LI>
<LI><CODE>column at index 3</CODE> - optional permanent endpoint prefixes (comma separated)</LI>
</UL>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
PermanentEndpointsQuery=SELECT peip, 1720, pealias, NULL FROM permanentep WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
<LI><CODE>GWPrefixesQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define a SQL query used to retrieve gateway prefixes from the database 
for the <CODE>[RasSrv::GWPrefixes]</CODE> section. The query is parameterized 
- that means parameter replacement is made before each query
is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... 
strings. Specify %% to embed a percent character before a digit into string 
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions 
like <B>%{1}123</B>. For <CODE>GWPrefixesQuery</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>

It is expected that the query returns zero or more rows of data,
with each row consisting of two columns:
<UL>
<LI><CODE>column at index 0</CODE> - gateway alias</LI>
<LI><CODE>column at index 1</CODE> - gateway prefixes (comma separated)</LI>
</UL>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
GWPrefixesQuery=SELECT gwalias, gwpfx FROM gwprefix WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
<P>
</LI>
</UL>
<P>
<H2><A NAME="monitor"></A> <A NAME="s13">13. Monitoring the Gatekeeper</A></H2>

<P>
<H2>13.1 Status Port</H2>

<P>The status port is the external interface for monitoring and controlling the gatekeeper.
The gatekeeper will send out messages about ongoing calls to all
connected clients and it can receive commands via this interface.
<P>Access to the status port is restricted by the rules in 
<A HREF="#gkstatusauth">GkStatus::Auth</A>.
For security reasons, the default is not to allow any access until you have
configured 
<A HREF="#gkstatusauth">GkStatus::Auth</A>.
<P>The messages sent by the gatekeeper to the status port are grouped 
into three <B>output trace levels</B>:
(These trace levels only apply to what is shown on the status port.
Don't confuse them with the trace level for GnuGk's trace file.)
<UL>
<LI>Level 0
<BLOCKQUOTE>
Reload notifications and direct replies to entered commands.
</BLOCKQUOTE>
</LI>
<LI>Level 1
<BLOCKQUOTE>
Reload notifications, direct replies to entered commands, CDRs and Route Requests.
</BLOCKQUOTE>
</LI>
<LI>Level 2
<BLOCKQUOTE>
Output everything (reload notifications, direct replies to entered commands, 
CDRs, Route Requests, RAS, ...). This is the <B>default</B> output level.
</BLOCKQUOTE>
</LI>
</UL>

The client connected to the status port can choose the output level it is interested in.
<P>
<P>The interface is a simple TCP port (default: 7000) which you can connect to with telnet or another client. One example of a different client is the Java GUI, aka GkGUI.
Another example is the Automatic Call Distribution application, aka GnuGk ACD.
<P>
<H3>Application Areas</H3>

<P>What you do with the powers of the Status Interface is up to you, but here are a few ideas:
<UL>
<LI>Call Monitoring</LI>
<LI>Monitoring the registered endpoints</LI>
<LI>Graphical User Interface for GnuGk
<BLOCKQUOTE>
See GkGUI.
</BLOCKQUOTE>
</LI>
<LI>Call Routing
<BLOCKQUOTE>
See GnuGk ACD.
</BLOCKQUOTE>
</LI>
<LI>Billing Applications
<BLOCKQUOTE>
Analyze the CDR messages and forward them to a billing application.
</BLOCKQUOTE>
</LI>
<LI>Interfacing external extensions
<BLOCKQUOTE>
If you don't want to publish the source code to additional features, just publish the core functionality and interface to it through the status interface and keep the external part private.
</BLOCKQUOTE>
</LI>
</UL>
<P>
<H3>Examples</H3>

<P>Suppose you are just interested in the CDRs (call detail records) and want to process them as a batch at regular intervals.
<P>Here is a simple Perl script (<CODE>gnugk_cdr.pl</CODE>) that starts the gatekeeper and also forks a very simple client for the Status Interface and writes just the CDRs into a logfile. You'll have to modify it a little to fit your needs.
<P>
<PRE>
#!/usr/bin/perl
# sample program that demonstrates how to write the CDRs to a log file
use strict;
use IO::Socket;
use IO::Handle;

my $logfile = "/home/jan/cdr.log";      # CHANGE THIS
my $gk_host = "localhost";
my $gk_port = 7000;
my $gk_pid;

if ($gk_pid = fork()) {
        # parent will listen to gatekeeper status
        sleep(1);       # wait for gk to start
        my $sock = IO::Socket::INET->new(PeerAddr => $gk_host, PeerPort => $gk_port, Proto => 'tcp');
        if (!defined $sock) {
                die "Can't connect to gatekeeper at $gk_host:$gk_port";
        }
        $SIG{HUP} = sub { kill 1, $gk_pid; };   # pass HUP to gatekeeper
        $SIG{INT} = sub { close (CDRFILE); kill 2, $gk_pid; };  # close file when terminated

        open (CDRFILE, ">>$logfile");
        CDRFILE->autoflush(1);  # don't buffer output
        while (!$sock->eof()) {
                my $msg = $sock->getline();
                $msg = (split(/;/, $msg))[0];   # remove junk at end of line
                my $msgtype = (split(/\|/, $msg))[0];
                if ($msgtype eq "CDR") {
                        print CDRFILE "$msg\n";
                }
        }
        close (CDRFILE);
} else {
        # child starts gatekeeper
        exec("gnugk");
}
</PRE>
<P>Keep in mind that this is just an example to show the usage of the status port.
You can use the FileAcct module to log CDRs in a production system.
<P>
<H3>Java GUI for the Gatekeeper</H3>

<P>Developed by Jan Willamowius.
<P>You can monitor the registrations and calls that go through the gatekeeper.
A right-click on a button gives you a pop up menu for that endpoint.
<P>This GUI works with Java 1.0 built into most web browsers.
For security reasons the GUI must be run as a standalone application
or served by a web server on the same IP number as the gatekeeper
(you cannot run it as an applet via a local file).
<P>The program is available at
<A HREF="http://www.gnugk.org/h323gui.html">GnuGk.org</A><P>
<H2>13.2 Commands (Reference)</H2>

<P>This section lists all commands that you can issue to the status port (manually or with an external application). Commands are not case-insensitive, but parameters may be. 
<P>Entering <CODE>help</CODE> or <CODE>h</CODE> will display a list of all available commands.
<P>
<UL>
<LI><CODE>Reload</CODE><BR>
<P>Reload the configuration.
<P>Reloading the configuration will not terminate existing calls, and any change to settings will only take effect
on new calls.
<P>You can add an optional parameter to reload only a part of your configuration:
<UL>
<LI>AcctConfig - reload only the accounting config</LI>
<LI>AuthConfig - reload only the authentication config</LI>
<LI>CapConfig - reload only the CapacityControl rules</LI>
<LI>EpConfig - reload only the endpoint config (permanent endpoints, endpoint section, call table settings)</LI>
</UL>
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
Reload
Full Config reloaded.

Reload EpConfig
EP Config reloaded.
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>Shutdown</CODE><BR>
<P>Terminate the gatekeeper. Can be disabled by Shutdown=forbid in section 
<A HREF="#gkstatusauth">[GkStatus::Auth]</A>.
<P>
</LI>
<LI><CODE>Version</CODE>, <CODE>v</CODE><BR>
<P>Show the version and OS information of the gatekeeper.
<P>
</LI>
<LI><CODE>Statistics</CODE>, <CODE>s</CODE><BR>
<P>Show the statistics information of the gatekeeper.
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
Statistics
-- Endpoint Statistics --
Total Endpoints: 21  Terminals: 17  Gateways: 4  NATed: 2
Cached Endpoints: 1  Terminals: 1  Gateways: 0
-- Call Statistics --
Current Calls: 1 Active: 1 From Neighbor: 0 From Parent: 0
Total Calls: 1539  Successful: 1076  From Neighbor: 60  From Parent: 5
Startup: Fri, 21 Jun 2002 10:50:22 +0800   Running: 11 days 04:22:59
;
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>ResetCallCounters</CODE><BR>
<P>Reset the statistics counters for total calls, successful calls, neighbor calls and parent calls to zero.
<P>
</LI>
<LI><CODE>PrintAllRegistrations</CODE>, <CODE>r</CODE>, <CODE>?</CODE><BR>
<P>Show all registered endpoints.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
AllRegistrations
RCF|IP:Port|Aliases|Terminal_Type|EndpointID
...
Number of Endpoints: n
;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
AllRegistrations
RCF|10.1.1.10:1720|800:dialedDigits=Wei:h323_ID|terminal|1289_endp
RCF|10.0.1.43:1720|613:dialedDigits=Jacky Tsai:h323_ID|terminal|1328_endp
RCF|10.0.1.55:1720|705:dialedDigits=Sherry Liu:h323_ID|terminal|1333_endp
Number of Endpoints: 3
;
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>PrintAllRegistrationsVerbose</CODE>, <CODE>rv</CODE>, <CODE>??</CODE><BR>
<P>Show details of all registered endpoints.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
AllRegistrations
RCF|IP:Port|Aliases|Terminal_Type|EndpointID
Registration_Time C(Active_Call/Connected_Call/Total_Call) &lt;r&gt;
[Prefixes: ##] (gateway only)
...
Number of Endpoints: n
;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
AllRegistrations
RCF|10.0.1.8:1720|Accel-GW2:h323_ID|gateway|1322_endp
Wed, 26 Jun 2002 16:40:03 +0800 C(1/5/33) &lt;1&gt;
Prefixes: 09,002
RCF|10.1.1.10:1720|800:dialedDigits=Wei:h323_ID|terminal|1289_endp
Wed, 26 Jun 2002 16:40:55 +0800 C(0/32/39) &lt;1&gt;
RCF|10.0.1.66:1720|716:dialedDigits=Vicky:h323_ID|terminal|1425_endp
Wed, 26 Jun 2002 16:40:58 +0800 C(1/47/53) &lt;1&gt;
Number of Endpoints: 2
;
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>PrintAllCached</CODE>, <CODE>rc</CODE><BR>
<P>Print list of all cached out-of-zone endpoints.
<P>
</LI>
<LI><CODE>PrintCurrentCalls</CODE>, <CODE>c</CODE>, <CODE>!</CODE><BR>
<P>Show all current calls using the same ACF syntax as in call establishment.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
CurrentCalls
Call No. # | CallID | Call_Duration | Left_Time
Dialed_Number
ACF|Caller_IP:Port|Caller_EPID|CRV|DestinationInfo|SrcInfo|IsAnswered;
ACF|Callee_IP:Port|Callee_EPID|CRV|DestinationInfo|SrcInfo|IsAnswered;
...
Number of Calls: Current_Call Active: Active_Call From Neighbor: Call_From_Neighbor \
From Parent: Call_From_Parent
;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
CurrentCalls
Call No. 29 | CallID bd c6 17 ff aa ea 18 10 85 95 44 45 53 54 77 77 | 109 | 491
Dial 0953378875:dialedDigits
ACF|10.0.1.49:1720|4048_CGK1|25263|frank:h323_ID|gunter:h323_ID|false;
ACF|10.1.1.1:1720|4037_CGK1|25263|gunter:h323_ID|frank:h323_ID|true;
Call No. 30 | CallID 70 0e dd c0 9a cf 11 5e 00 01 00 05 5d f9 28 4d | 37 | 563
Dial 0938736860:dialedDigits
ACF|10.0.1.48:1032|4041_CGK1|11896|sue:h323_ID|peter:h323_ID|false;
ACF|10.1.1.1:1720|4037_CGK1|11896|peter:h323_ID|sue:h323_ID|true;
Number of Calls: 2 Active: 2 From Neighbor: 0 From Parent: 0
;
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>PrintCurrentCallsVerbose</CODE>, <CODE>cv</CODE>, <CODE>!!</CODE><BR>
<P>Show details of all current calls.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
CurrentCalls
Call No. # | CallID | Call_Duration | Left_Time
Dialed_Number
ACF|Caller_IP:Port|Caller_EPID|CRV|DestinationInfo|SrcInfo|IsAnswered;
ACF|Callee_IP:Port|Callee_EPID|CRV|DestinationInfo|SrcInfo|IsAnswered;
# Caller_Aliases|Callee_Aliases|Bandwidth|Connected_Time &lt;r&gt;
...
Number of Calls: Current_Call Active: Active_Call From NB: Call_From_Neighbor
;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
CurrentCalls
Call No. 48 | CallID 7d 5a f1 0a ad ea 18 10 89 16 00 50 fc 3f 0c f5 | 30 | 570
Dial 0225067272:dialedDigits
ACF|10.0.1.200:1720|1448_endp|19618|frank:h323_ID|gunter:h323_ID|false;
ACF|10.0.1.7:1720|1325_endp|19618|gunter:h323_ID|frank:h323_ID|true;
# Sherry:h323_ID|Accel-GW1:h323_ID|200000|Wed, 26 Jun 2002 17:29:55 +0800 &lt;2&gt;
Number of Calls: 1 Active: 1 From NB: 0
;
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>PrintPrefixCapacities</CODE>, <CODE>printpc</CODE><BR>
<P>Print the prefix capacities and current counter values for all endpoints
or the specified alias.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
PrintPrefixCapacities [Alias]
PrefixCapacities
-- Endpoint: Alias (1.2.3.4:1720) --
Total calls = 0
prefix/capacity/curr: 125/5/0
-- Endpoint: Alias2 (1.2.3.5:1720) --
Total calls = 0
prefix/capacity/curr: 125/5/0
;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
PrintPrefixCapacities OpenMCU
PrefixCapacities
-- Endpoint: OpenMCU (192.168.1.100:1720) --
Total calls = 0
prefix/capacity/curr: ^(123|124)/2/0
prefix/capacity/curr: 125/5/0
;
</PRE>
</CODE></BLOCKQUOTE>
</DL>
</LI>
<LI><CODE>printcc</CODE><BR>
<P>Print the current counters for all CapacityControl rules.
<P>
</LI>
<LI><CODE>Find</CODE>, <CODE>f</CODE><BR>
<P>Find a registered endpoint by an alias or a prefix. To find an alias
of the specified type (h323_ID, dialedDigits), prepend the alias type name
(h323, e164, url, email) to the alias, followed by a colon.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
Find Alias
RCF|IP:Port|Aliases|Terminal_Type|EndpointID
;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
f 800
RCF|10.1.1.10:1720|800:dialedDigits=Wei:h323_ID|terminal|1289_endp
;
f 801
Alias 801 not found!
f h323:Wei
RCF|10.1.1.10:1720|800:dialedDigits=Wei:h323_ID|terminal|1289_endp
;
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>FindVerbose</CODE>, <CODE>fv</CODE><BR>
<P>Find details of a registered endpoint by an alias or a prefix. To find an alias
of the specified type (h323_ID, dialedDigits), prepend the alias type name
(h323, e164, url, email) to the alias, followed by a colon.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
FindVerbose Alias
RCF|IP:Port|Aliases|Terminal_Type|EndpointID
Registration_Time C(Active_Call/Connected_Call/Total_Call) &lt;r&gt;
[Prefixes: ##] (gateway only)
;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
fv 02
RCF|10.0.1.100:1720|TFN:h323_ID|gateway|4037_CGK1
Wed, 26 Jun 2002 17:47:29 +0800 C(0/84/120) &lt;1&gt;
Prefixes: 02,09
;
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>UnregisterIP</CODE><BR>
<P>Forcefully unregister an endpoint by IP and call signaling port.
If you don't specify a call signal port, GnuGk will unregister
the first endpoint it finds on the IP number
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
UnregisterIP IP[:Port]
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
UnregisterIP 10.0.1.31:1720
URQ|10.0.1.31:1032|1326_endp|maintenance;
Endpoint 10.0.1.31:1720 unregistered!
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>UnregisterAlias</CODE><BR>
<P>Forcefully unregister an endpoint by one of its aliases. To match an alias
of the specified type (h323_ID, dialedDigits), prepend the alias type name
(h323, e164, url, email) to the alias, followed by a colon.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
UnregisterAlias Alias
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
UnregisterAlias 601
URQ|10.0.1.31:1032|1326_endp|maintenance;
Endpoint 601 unregistered!
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>UnregisterAllEndpoints</CODE><BR>
<P>Forcefully unregister all registered endpoints.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
UnregisterAllEndpoints
URQ|10.0.1.7:1024|1325_endp|maintenance;
URQ|10.0.1.8:1024|1322_endp|maintenance;
URQ|10.0.1.32:1032|1324_endp|maintenance;
URQ|10.0.1.36:1032|1323_endp|maintenance;
URQ|10.0.1.42:1032|1318_endp|maintenance;
Done
;
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>DisconnectCall</CODE><BR>
<P>Disconnect a call with given number (internal, gatekeeper assigned call number,
not the caller's, callee's phone number).
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
DisconnectCall Number
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
DisconnectCall 1533
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>DisconnectIP</CODE><BR>
<P>Disconnect all calls of an endpoint by IP and call signaling port.
If you don't specify a call signal port, GnuGk will disconnect the
first endpoint it finds on the IP number
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
DisconnectIP IP[:Port]
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
DisconnectIP 10.0.1.31:1720
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>DisconnectAlias</CODE><BR>
<P>Disconnect all calls of an endpoint by one of its aliases. To match an alias
of the specified type (h323_ID, dialedDigits), prepend the alias type name
(h323, e164, url, email) to the alias, followed by a colon.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
DisconnectAlias Alias
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
DisconnectAlias 601
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>ClearCalls</CODE><BR>
<P>Disconnect all calls on the gatekeeper.
<P>
</LI>
<LI><CODE>GK</CODE><BR>
<P>Show the information of the parent gatekeeper.
<P>
</LI>
<LI><CODE>Trace</CODE><BR>
<P>Set the status interface output trace level. It controls which messages
are sent to this client:
<UL>
<LI><CODE>trace 0</CODE> or <CODE>trace min</CODE><BR>
<P>Only direct responses to commands and reload notifications.
</LI>
<LI><CODE>trace 1</CODE><BR>
<P>CDRs, direct responses to commands and reload notifications.
</LI>
<LI><CODE>trace 2</CODE> or <CODE>trace max</CODE><BR>
<P>Show all (RAS, CDRs, direct responses to commands, reload notifications, etc).
</LI>
</UL>
<P>
</LI>
<LI><CODE>Debug</CODE><BR>
<P>Only used for debug purpose. Options:
<UL>
<LI><CODE>trc [+|-|n]</CODE><BR>
<P>Show/modify trace level.
</LI>
<LI><CODE>cfg SEC PAR</CODE><BR>
<P>Read and print a config parameter in a section.
</LI>
<LI><CODE>set SEC PAR VAL</CODE><BR>
<P>Write a config value parameter in a section.
</LI>
<LI><CODE>remove SEC PAR</CODE><BR>
<P>Remove a config value parameter in a section.
</LI>
<LI><CODE>remove SEC</CODE><BR>
<P>Remove a section.
</LI>
<LI><CODE>printrm VERBOSE</CODE><BR>
<P>Print all removed endpoint records.
</LI>
</UL>

<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
debug trc 3
debug set RoutedMode H245Routed 1
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>SetLog</CODE><BR>
<P>Send trace output to another file.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
Setlog [filename]
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
Setlog /tmp/trace.log
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>RotateLog</CODE><BR>
<P>Rotate the log file.
<P>
</LI>
<LI><CODE>Who</CODE><BR>
<P>Show all people on the status port.  First field is the session id, which can be used to disconnect
a user through the DisconnectSession command.
<P>
</LI>
<LI><CODE>DisconnectSession</CODE><BR>
<P>Disconnect a user from the status port.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
DisconnectSession [session id]
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
DisconnectSession 2
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>Yell</CODE>, <CODE>y</CODE><BR>
<P>Send a message to all status clients.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
Yell [message text]
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
Yell Config reload in 5 minutes.
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>RouteReject</CODE><BR>
<P>Terminate this call on a virtual queue.
This command is used as a response to a RouteRequest event (see below).
CallingEndpointID and CallRef must be passed back as they are in the corresponding RouteRequest.
The CallID parameter is optional; if it is given it has to be the same format as
signaled by RouteRequest.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
RouteReject CallingEndpointID CallRef [CallID]
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
RouteReject endp_4711 1234
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>RouteToAlias</CODE>, <CODE>rta</CODE><BR>
<P>Route this call on a virtual queue to the specified alias.
This command is used as a response to a RouteRequest event (see below).
CallingEndpointID and CallRef must be passed back as they are in the corresponding RouteRequest.
The CallID parameter is optional; if it is given it has to be the same format as
signaled by RouteRequest.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
RouteToAlias Alias CallingEndpointID CallRef [CallID]
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
RouteToAlias Suzi endp_4711 1234
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>RouteToGateway</CODE>, <CODE>rtg</CODE><BR>
<P>Route this call on a virtual queue to the specified alias and set the destinationSignalAddress.
This command is used as a response to a RouteRequest event (see below).
You can use this command to route calls to out-of-zone gateways or MCUs not registered with the gatekeeper. Make sure that the 'vqueue' and 'explicit' policy is in effect for these calls.
CallingEndpointID and CallRef must be passed back as they are in the corresponding RouteRequest.
The CallID parameter is optional; if it is given it must be the same format as
signaled by RouteRequest.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
RouteToGateway Alias IP:Port CallingEndpointID CallRef [CallID]
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
RouteToGateway Suzi 192.168.0.50 endp_4711 1234
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>BindAndRouteToGateway</CODE><BR>
<P>This command is similar to RouteToGateway, but you can also specify which
IP of a multi-homed server to use for the outgoing call.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
BindAndRouteToGateway IP Alias IP:Port CallingEndpointID CallRef [CallID]
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
BindAndRouteToGateway 192.168.0.2 Suzi 192.168.0.50 endp_4711 1234
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>SendProceeding</CODE><BR>
<P>WARNING: This is an experimental feature.
<P>Send a CallProceeding message to the caller.
The only time this makes sense is after a RouteRequest event for an unregistered call.
Otherwise a status port application won't know if a Setup message has been sent but that
the call is not yet established.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
SendProceeding CallID
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
SendProceeding 40-06-dd-98-22-37-52-40-8c-b0-92-0e-18-60-99-07
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>Exit</CODE>, <CODE>Quit</CODE>, <CODE>q</CODE>, <CODE>Ctrl-D</CODE><BR>
<P>Quit the status port.
<P>
</LI>
<LI><CODE>TransferCall</CODE><BR>
<P>Transfer an established call from alias A to alias B. 
<P>This works only with endpoints that properly support
Q.931 Facility messages (so it doesn't work with Netmeeting).
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
TransferCall Source-Alias New-Destination-Alias
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
TransferCall Frank Peter
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
<A NAME="makecall"></A> </LI>
<LI><CODE>MakeCall</CODE><BR>
<P>Generate a new call from source to destination alias. You can also
specify an IP number as destination.  This is done by establishing a call
from a pseudo endpoint in the gatekeeper to the source alias/number and then
transferring the call from the gatekeeper endpoint to the destination.
<P>The transfer can be done using either a H.450.2 transfer or a Facility message.
<P>See 
<A HREF="#ctimakecall">[CTI::MakeCall]</A> for configuration options.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
MakeCall Source-Alias Destination-Alias
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
MakeCall 1234 5678
MakeCall joe 192.168.6.1
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>GetAuthInfo,gai</CODE><BR>
<P>Gather information from a specific authentication module (if it provides
such information) and displays it on the status port.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
GetAuthInfo ModuleName
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
GetAuthInfo RadAliasAuth
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
<LI><CODE>GetAcctInfo,gci</CODE><BR>
<P>Gather information from a specific accounting module (if it provides
such information) and displays it on the status port.
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
GetAcctInfo ModuleName
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
GetAcctInfo SqlAcct
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
</LI>
</UL>
<P>
<H2>13.3 Messages (Reference)</H2>

<P>The section describes the messages output to the status interface.
<P>
<UL>
<LI><CODE>GCF|IP|Aliases|Endpoint_Type;</CODE><BR>
<P>The gatekeeper receives a GatekeeperRequest (GRQ) and responds with
a GatekeeperConfirm (GCF).
<P>
</LI>
<LI><CODE>GRJ|IP|Aliases|Endpoint_Type|RejectReason;</CODE><BR>
<P>The gatekeeper receives a GatekeeperRequest (GRQ) and responds with
a GatekeeperReject (GRJ).
<P>
</LI>
<LI><CODE>RCF|IP:Port|Aliases|Endpoint_Type|EndpointID;</CODE><BR>
<P>The gatekeeper receives a RegistrationRequest (RRQ) and responds with
a RegistrationConfirm (RCF).
<P>
</LI>
<LI><CODE>RRJ|IP|Aliases|Endpoint_Type|RejectReason;</CODE><BR>
<P>The gatekeeper receives a RegistrationRequest (RRQ) and responds with
a RegistrationReject (RRJ).
<P>
</LI>
<LI><CODE>ACF|Caller_IP:Port|Caller_EndpointID|CRV|DestinationInfo|SrcInfo|IsAnswered|CallID;</CODE><BR>
<P>The gatekeeper receives an AdmissionRequest (ARQ) and responds with
an AdmissionConfirm (ACF).
<P>
</LI>
<LI><CODE>ARJ|Caller_IP:Port|DestinationInfo|SrcInfo|IsAnswered|RejectReason|CallID;</CODE><BR>
<P>The gatekeeper receives an AdmissionRequest (ARQ) and responds with
an AdmissionReject (ARJ).
<P>
</LI>
<LI><CODE>DCF|IP|EndpointID|CRV|DisengageReason|CallID;</CODE><BR>
<P>The gatekeeper receives a DisengageRequest (DRQ) and responds with
a DisengageConfirm (DCF).
<P>
</LI>
<LI><CODE>DRJ|IP|EndpointID|CRV|RejectReason|CallID;</CODE><BR>
<P>The gatekeeper receives a DisengageRequest (DRQ) and responds with
a DisengageReject (DRJ).
<P>
</LI>
<LI><CODE>LCF|IP|EndpointID|DestinationInfo|SrcInfo;</CODE><BR>
<P>The gatekeeper receives a LocationRequest (LRQ) and responds with
a LocationConfirm (LCF).
<P>
</LI>
<LI><CODE>LRJ|IP|DestinationInfo|SrcInfo|RejectReason;</CODE><BR>
<P>The gatekeeper receives a LocationRequest (LRQ) and responds with
a LocationReject (LRJ).
<P>
</LI>
<LI><CODE>BCF|IP|EndpointID|Bandwidth;</CODE><BR>
<P>The gatekeeper receives a BandwidthRequest (BRQ) and responds with
a BandwidthConfirm (BCF).
<P>
</LI>
<LI><CODE>BRJ|IP|EndpointID|Bandwidth|RejectReason;</CODE><BR>
<P>The gatekeeper receives a BandwidthRequest (BRQ) and responds with
a BandwidthReject (BRJ).
<P>
</LI>
<LI><CODE>UCF|IP|EndpointID;</CODE><BR>
<P>The gatekeeper receives an UnregistrationRequest (URQ) and responds with
an UnregistrationConfirm (UCF).
<P>
</LI>
<LI><CODE>URJ|IP|EndpointID|RejectReason;</CODE><BR>
<P>The gatekeeper receives an UnregistrationRequest (URQ) and responds with
an UnregistrationReject (URJ).
<P>
</LI>
<LI><CODE>IRQ|IP:Port|EndpointID;</CODE><BR>
<P>The gatekeeper sends an InfoRequest (IRQ) to an endpoint to query if it
is still alive. The endpoint must immediately respond with an InfoRequestResponse (IRR).
<P>
</LI>
<LI><CODE>URQ|IP:Port|EndpointID|Reason;</CODE><BR>
<P>The gatekeeper sends an UnregistrationRequest (URQ) to an endpoint to
cancel its registration. The endpoint shall respond with
an UnregistrationConfirm (UCF).
<P>
</LI>
<LI><CODE>CDR|CallNo|CallId|Duration|Starttime|Endtime|CallerIP|CallerEndId|</CODE> \<BR>
<CODE>CalledIP|CalledEndId|DestinationInfo|SrcInfo|GatekeeperID;</CODE><BR>
<P>After a call disconnected, the call detail record is shown (in one line).
<P>
</LI>
<LI><CODE>RouteRequest|CallerIP:Port|CallerEndpointId|CallRef|VirtualQueue|CallerAlias|CallID|CalledIP:Port;</CODE><BR>
<P>Request for an external application to route an incoming call on a virtual queue.
This can be done with a RouteToAlias or RouteReject command.
<P>
</LI>
</UL>
<P>
<H2><A NAME="statusportfiltering"></A> 13.4 Status Port Filtering</H2>

<P>Status port filtering facilitates control of the amount and type of output messages shown to the end user.
Filtering is done using regular expressions which are used to decide whether to include (show) or
exclude (ignore) an output message.
Filtering control is performed using the following set of commands:
<P>
<UL>
<LI><CODE>addincludefilter REGEX</CODE><BR>
Adds regular expression to the include list
</LI>
<LI><CODE>addexcludefilter REGEX</CODE><BR>
Adds regular expression to the exclude list
</LI>
<LI><CODE>removeincludefilter INDEX</CODE><BR>
Removes filter at given INDEX from the include list
</LI>
<LI><CODE>removeexcludefilter INDEX</CODE><BR>
Removes filter at given INDEX from the exclude list
</LI>
<LI><CODE>filter 1|0</CODE><BR>
Enable/Disable message filtering
</LI>
<LI><CODE>printincludefilters</CODE><BR>
Print include filter list
</LI>
<LI><CODE>printexcludefilters</CODE><BR>
Print exclude filter list
</LI>
</UL>
<P>In order to enable usage of predefined filters, a new section named 
<A HREF="#gkstatusfilteringsect">[GkStatus::Filtering]</A> has been
introduced. You may specify predefined filters to be loaded when the status port starts.
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[GkStatus::Filtering]
IncludeFilter=.+
ExcludeFilter=.RQ
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>When filtering is enabled using the the <CODE>filter 1</CODE> command, all messages will be shown other than lines with ARQ, LRQ etc.
You may also type the following into the status port:
<BLOCKQUOTE><CODE>
<PRE>
addincludefilter .+
addexcludefilter .RQ
filter 1
</PRE>
</CODE></BLOCKQUOTE>
<P>Note that enable filtering when there are no filters defined will automatically exclude all message output.
<P>
<H2><A NAME="s14">14. Advanced Topics</A></H2>

<P>This portion of the manual will cover advanced topics, such as compiling GnuGk.
<P>
<H2><A NAME="compile"></A> 14.1 Compiling GnuGk</H2>

<P>The following instructions are an example of how to compile GnuGK from source on an Ubuntu platform.
<PRE>
$ sudo apt-get update
$ sudo apt-get install flex bison build-essential subversion cvs pkg-config
</PRE>
<P>Get and compile ptlib from SourceForge
<PRE>
$ cd ~
$ svn co http://opalvoip.svn.sourceforge.net/svnroot/opalvoip/ptlib/trunk ptlib
$ cd ptlib
$ export PTLIBDIR=~/ptlib
$ ./configure
$ make optnoshared
</PRE>
<P>Get and compile h323plus:
<PRE>
$ cd ~
$ cvs -d:pserver:anonymous@h323plus.cvs.sourceforge.net:/cvsroot/h323plus login

(just press enter when prompted for password)

$ cvs -z3 -d:pserver:anonymous@h323plus.cvs.sourceforge.net:/cvsroot/h323plus co -P h323plus

$ cd h323plus
$ export OPENH323DIR=~/h323plus
$ ./configure
$ make optnoshared
</PRE>
<P>Get and compile GnuGk:
<PRE>
$ cvs -d:pserver:anonymous@openh323gk.cvs.sourceforge.net:/cvsroot/openh323gk login

(just press enter when prompted for password)

$ cvs -z3 -d:pserver:anonymous@openh323gk.cvs.sourceforge.net:/cvsroot/openh323gk co -P openh323gk

$ cd openh323gk
$ ./configure --enable-h46018
$ make optnoshared
</PRE>
<P>Once the compile is finished, the binary can be found in the 
obj_linux_x86_s subdirectory.
<P>At this time, because all libraries and GnuGk are running CVS and svn 
versions of the software, in order to stay up-to-date, run the following:
<P>
<PRE>
$ cd ~/ptlib
$ svn up
$ cd ~/h323plus
$ cvs up
$ cd ~/openh323gk
$ cvs up
</PRE>

If any of the source files are changed, you may need to recompile.
<P>
<H2><A NAME="debug"></A> 14.2 Debugging GnuGk</H2>

<P>In order to use gdb with GnuGk, the software and libraries must be compiled with debug support.
<P>You may follow the instructions above in obtaining the software, but the compile in each subdirectory must be:
<PRE>
$ make debug
</PRE>
<P>Configure your CLI to allow unlimited core files:
<PRE>
ulimit -c unlimited
</PRE>
<P>Because the <CODE>make debug</CODE> creates dynamically linked libraries, execute the following:
<PRE>
export LD_LIBRARY_PATH=$PTLIBDIR/lib_linux_x86:$OPENH323DIR/lib
</PRE>
<P>Run GnuGk:
<PRE>
~/openh323/obj_linux_x86_64_d/gnugk -c your.ini
# wait for crash
gdb obj_linux_x86_64_d/gnugk core
bt
</PRE>
<P>Once you've obtained a backtrace, post it to the mailing list.
<P>
<P>
</BODY>
</HTML>
